Skip to main content

​
Starting FERAL

After installation, start everything with a single command: 
feral start
This launches three components simultaneously:
ComponentDescriptionDefault Address
BrainPython backend — LLM orchestration, memory, skills, hardware meshws://localhost:9090
DashboardReact web UI — The Orb, timeline, ambient strip, SDUI rendererhttp://localhost:3000
REPLInteractive terminal session for text commandsYour terminal
On first launch, FERAL detects that no configuration exists and automatically runs the setup wizard.

​
The Setup Wizard

If you haven’t configured FERAL yet, run the wizard explicitly: 
feral setup
1

Choose your LLM provider

The wizard lists available providers. Pick one:
? Select your LLM provider:
  ❯ Ollama (local, no API key needed)
    Anthropic (Claude)
    OpenAI (GPT-4)
    OpenRouter (multi-model gateway)
    Google Gemini
Select Ollama for a fully local setup with zero cloud dependency. FERAL auto-detects Ollama running on localhost:11434.
2

Enter your API key (if applicable)

For cloud providers, paste your key. It gets encrypted and stored in ~/.feral/credentials.json.
? Enter your Anthropic API key: sk-ant-••••••••
✓ Key validated and stored in credential vault.
3

Create your identity (USER.md)

FERAL asks for your name, preferences, and context. This becomes your USER.md file — the foundation of how FERAL personalizes responses.
? Your name: Alex
? How should FERAL address you? Alex
? Describe yourself in a sentence: Software engineer, night owl, into running.
✓ USER.md created at ~/.feral/USER.md
You can edit USER.md at any time to refine your identity.
4

Configure autonomy level

Choose how much freedom FERAL has:
? Autonomy mode:
  ❯ Hybrid (safe actions auto-execute, risky ones ask first)
    Strict (everything requires approval)
    Loose (full autopilot)
5

Hardware scan (optional)

FERAL scans for nearby BLE devices and Home Assistant instances:
Scanning for hardware…
✓ Found: FERAL-Wristband-A3F2 (BLE)
✓ Found: Home Assistant at 192.168.1.50:8123
? Connect to these devices now? (Y/n)

​
Your First Conversation

Once setup completes, you are dropped into the REPL. Try these: 
> Hey FERAL, what can you do?
Open the dashboard at http://localhost:3000 to see The Orb — FERAL’s visual presence — react to your conversation in real time.

​
What’s Running

Use feral status to check all active components: 
$ feral status

  Brain       ● running   ws://localhost:9090   PID 48201
  Dashboard   ● running   http://localhost:3000  PID 48215
  Voice       ● active    wake word listening
  Hardware    ● 2 devices FERAL-Wristband-A3F2, Home-Assistant
  Memory      ● sqlite    ~/.feral/memory.db (24 episodes)
  Autonomy    ● hybrid    3 safe / 2 risky categories

​
Stopping FERAL

feral stop          # graceful shutdown of all components
Or press Ctrl+C in the REPL to stop the brain and dashboard together.

​
Next Steps

Configuration

Customize settings, swap LLM models, tune autonomy.

Voice Setup

Configure wake word detection and streaming voice providers.

Connect Hardware

Pair your wristband and start streaming biometrics.

Build Skills

Extend FERAL with custom plugins.