Installation

Prerequisites

Before installing FERAL, make sure you have the following:

Dependency	Minimum Version	Check Command
Python	3.11+	`python3 --version`
Node.js	20+	`node --version`
pip	Latest	`pip --version`
Git	Any recent	`git --version`

macOS users can install prerequisites with brew install python@3.11 node. Linux users should use their system package manager.

Choose Your Install Path

One-Liner (Recommended)
Git Clone
Docker

The install script creates a virtual environment at ~/.feral-env, installs all dependencies, and adds feral to your PATH.

Run the installer

curl -sSL https://raw.githubusercontent.com/FERAL-AI/FERAL-AI/main/scripts/install.sh | bash

Activate the environment

source ~/.feral-env/bin/activate

Verify the install

feral --version
feral doctor

Add source ~/.feral-env/bin/activate to your .bashrc or .zshrc so FERAL is always available.

Clone the repo and install manually for full control.

Clone the repository

git clone https://github.com/FERAL-AI/FERAL-AI.git
cd FERAL-AI

Install the brain (feral-core)

make install

cd feral-core
pip install -e ".[llm]"

Install the dashboard (feral-client-v2)

cd feral-client-v2
npm install

Verify the install

feral --version
feral doctor

Run everything in containers — no local Python or Node needed.

Clone the repository

git clone https://github.com/FERAL-AI/FERAL-AI.git
cd FERAL-AI

Start the containers

docker compose up

This starts the brain on port 9090 with the web dashboard bundled.

Open the dashboard

Navigate to http://localhost:9090 in your browser.

Docker mode does not support direct BLE hardware connections. Use the native install for wristband or smart-home control.

Post-Install

After any install path, run the setup wizard to configure your LLM provider and identity:

feral setup

This walks you through choosing a model provider, setting API keys, and creating your USER.md identity file. See First Run for a full walkthrough.

Troubleshooting

command not found: feral

The feral binary is not on your PATH. If you used the one-liner, activate the environment:

source ~/.feral-env/bin/activate

If you installed via git clone, ensure feral-core is installed in your active Python environment.

pip install fails with resolver errors

Pin your pip to the latest version and retry:

pip install --upgrade pip
pip install -e ".[llm]"

Node.js version too old

FERAL’s dashboard requires Node 20+. Use nvm to manage versions:

nvm install 20
nvm use 20

Docker compose fails to build

Make sure Docker Desktop is running and you have at least 4 GB of RAM allocated. Pull fresh base images:

docker compose build --no-cache

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Installation

Prerequisites

Choose Your Install Path

Post-Install

Troubleshooting

​Prerequisites

​Choose Your Install Path

​Post-Install

​Troubleshooting

Prerequisites

Choose Your Install Path

Post-Install

Troubleshooting