Need help with mycroft-core?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

5.4K Stars 1.1K Forks Apache License 2.0 4.8K Commits 166 Opened issues


Mycroft Core, the Mycroft Artificial Intelligence platform.

Services available


Need anything else?

Contributors list

License CLA Team Status

Unit Tests codecov PRs Welcome Join chat


Mycroft is a hackable open source voice assistant.

Table of Contents

Getting Started

First, get the code on your system! The simplest method is via git (git installation instructions): -

cd ~/
git clone
cd mycroft-core

This script sets up dependencies and a virtualenv. If running in an environment besides Ubuntu/Debian, Arch or Fedora you may need to manually install packages as instructed by

NOTE: The default branch for this repository is 'dev', which should be considered a work-in-progress. If you want to clone a more stable version, switch over to the 'master' branch.

Running Mycroft

Mycroft provides
to perform common tasks. This script uses a virtualenv created by
. Assuming you installed mycroft-core in your home directory run: -
cd ~/mycroft-core
./ debug

The "debug" command will start the background services (microphone listener, skill, messagebus, and audio subsystems) as well as bringing up a text-based Command Line Interface (CLI) you can use to interact with Mycroft and see the contents of the various logs. Alternatively you can run

./ all
to begin the services without the command line interface. Later you can bring up the CLI using
./ cli

The background services can be stopped as a group with: -


Using Mycroft

Home Device and Account Manager

Mycroft AI, Inc. maintains a device and account management system known as Mycroft Home. Developers may sign up at:

By default, mycroft-core is configured to use Home. By saying "Hey Mycroft, pair my device" (or any other request verbal request) you will be informed that your device needs to be paired. Mycroft will speak a 6-digit code which you can enter into the pairing page within the Mycroft Home site.

Once paired, your unit will use Mycroft API keys for services such as Speech-to-Text (STT), weather and various other skills.


Mycroft is nothing without skills. There are a handful of default skills that are downloaded automatically to your

directory, but most need to be installed explicitly. See the Skill Repo to discover skills made by others. Please share your own interesting work!

Behind the scenes

Pairing Information

Pairing information generated by registering with Home is stored in:



Mycroft's configuration consists of 4 possible locations: -

(Defaults) - Mycroft Home (Remote) -
(Machine) -
(which is by default
) (USER)

When the configuration loader starts, it looks in these locations in this order, and loads ALL configurations. Keys that exist in multiple configuration files will be overridden by the last file to contain the value. This process results in a minimal amount being written for a specific device and user, without modifying default distribution files.

Using Mycroft Without Home

If you do not wish to use the Mycroft Home service, before starting Mycroft for the first time, create

with the following contents:
  "skills": {
    "blacklisted_skills": [

API Key Services

The Mycroft backend provides access to a range of API keys for specific services. Without pairing with the Mycroft backend, you will need to add your own API keys, install a different Skill or Plugin to perform that function, or not have access to that functionality.

These are the keys currently used in Mycroft Core through the Mycroft backend:

Using Mycroft behind a proxy

Many schools, universities and workplaces run a

on their network. If you need to type in a username and password to access the external internet, then you are likely behind a

If you plan to use Mycroft behind a proxy, then you will need to do an additional configuration step.

NOTE: In order to complete this step, you will need to know the

for the proxy server. Your network administrator will be able to provide these details. Your network administrator may want information on what type of traffic Mycroft will be using. We use
traffic on port
, primarily for accessing ReST-based APIs.

Using Mycroft behind a proxy without authentication

If you are using Mycroft behind a proxy without authentication, add the following environment variables, changing the
for the values for your network. These commands are executed from the Linux command line interface (CLI).
$ export http_proxy=
$ export https_port=
$ export no_proxy="localhost,,localaddress,,,::1"

Using Mycroft behind an authenticated proxy

If you are behind a proxy which requires authentication, add the following environment variables, changing the
for the values for your network. These commands are executed from the Linux command line interface (CLI).
$ export http_proxy=http://user:[email protected]
$ export https_port=http://user:[email protected]
$ export no_proxy="localhost,,localaddress,,,::1"

Getting Involved

This is an open source project. We would love your help. We have prepared a contributing guide to help you get started.

If this is your first PR, or you're not sure where to get started, say hi in Mycroft Chat and a team member would be happy to mentor you. Join the Mycroft Forum for questions and answers.


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.