Welcome to Neon AI

Neon AI is an open source voice assistant. Follow these instructions to start using Neon on your computer. If you are using a Raspberry Pi, you may use the prebuilt image available on our website.

Quick Start with Docker

The fastest method for getting started with Neon is to run the modules in Docker containers. The docker directory contains everything you need to run Neon Core with default skills.

a. Prerequisite Setup

You will need docker and docker-compose available. Docker provides updated guides for installing docker and docker-compose. Neon Core is only tested on Ubuntu, but should be compatible with any linux distribution that uses PulseAudio.

Note: By default, only the root user has permissions to interact with Docker under Ubuntu. To allow the current user to modify Docker containers, you can add them to the docker group with:

sudo usermod -aG docker $USER && newgrp

b. Running Neon

You can clone the repository, or just copy the docker directory contents onto your local system; this document will assume that the repository is cloned to: ~/NeonCore.

Note: The docker directory includes required hidden files. If you copy files, make sure to include any hidden files. In must Ubuntu distros, you can toggle hidden file visibility in the file explorer with CTRL + h.

Note: If you run docker commands with sudo, make sure to use the -E flag to preserve runtime envvars.

Note: Some Docker implementations don't handle relative paths. If you encounter errors, try updating the paths in .env to absolute paths. Also note that any environment variables will override the default values in .env. In BASH shells, you can list all current envvars with env

You can start all core modules with:

# cd into the directory containing docker-compose.yml
cd ~/NeonCore/docker
docker-compose up -d

Stop all modules with:

# cd into the directory containing docker-compose.yml
cd ~/NeonCore/docker
docker-compose down

Optional GUI

The Mycroft GUI is an optional component that can be run on Linux host systems. The GUI is available with instructions on GitHub

c. Interacting with Neon

With the containers running, you can interact with Neon by voice (i.e. "hey Neon, what time is it?"), or using one of our CLI utilities, like mana or the neon_cli_client. You can view module logs via docker with:

docker logs -f neon-skills      # skills module
docker logs -f neon-speech      # voice module (STT and WW)
docker logs -f neon-audio       # audio module (TTS)
docker logs -f neon-gui         # gui module (Optional)
docker logs -f neon-messagebus  # messagebus module (includes signal manager)

d. Skill Development

By default, the skills container includes a set of default skills to provide base functionality. To add more skills to your installation, check out Configuring Extra Skills. Alternatively, you can pass a local skill directory into the skills container to load skills that are under development. Just set the environment variable NEON_SKILLS_DIR before starting the skills module. Dependency installation is handled on container start automatically.

export NEON_SKILLS_DIR=~/PycharmProjects/SKILLS
cd ~/NeonCore/docker
docker-compose up

To run the skills module without any bundled skills, the image referenced in docker-compose.yml can be changed from:

  neon-skills:
    container_name: neon-skills
    image: ghcr.io/neongeckocom/neon_skills-default_skills:dev

to:

  neon-skills:
    container_name: neon-skills
    image: ghcr.io/neongeckocom/neon_skills:dev

e. Persistent Data

The xdg/config directory is mounted to each of the Neon containers as XDG_CONFIG_HOME. xdg/config/neon/neon.yaml can be modified to change core configuration values. xdg/config/neon/skills contains settings files for each loaded skill

The xdg/data directory is mounted to each of the Neon containers as XDG_DATA_HOME. xdg/data/neon/filesystem contains skill filesystem files. xdg/data/neon/resources contains user skill resource files.

The xdg/cache directory is mounted to each of the Neon containers as XDG_CACHE_HOME. Any cache information should be recreated as needed if manually removed and includes things like STT/TTS model files, TTS audio files, and other downloaded files.

Note: When Docker creates files on the host filesystem, they are owned by root. In order to modify anything in the xdg directory, you may need to take ownership with: sudo chown -R $USER:$USER xdg

Troubleshooting

Here are some common questions and answers that come up during installation:

Images fail to pull

Make sure you have at least ~10GB of free space to pull images.

docker image prune –a can help free up space if you have old images left over after updates

Permissions errors/unable to run `docker` commands

By default, users are not given access to docker, this can be fixed by running:

sudo usermod -aG docker $USER && newgrp docker

If you still have permissions issues, try restarting before re-running any docker command.

Something went wrong in Neon

A good first step to troubleshooting issues in Neon is to restart the containers with a clean configuration. To stop the containers and remove configuration:

docker compose down
docker volume rm docker_config
docker volume rm docker_xdg

This stops the containers and removes any configuration, cache, and data files.

To make sure the latest images are available:

docker compose pull

Finally, bring the containers back up with:

docker compose up -d

Table of Contents