Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.feral.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
General

FERAL is a local-first AI runtime that coordinates tools, memory, channels, and device actions from one brain process.It can run only on your machine, or integrate with cloud providers depending on your chosen setup.
ChatGPT / SiriFERAL
Runs whereTheir cloud serversYour machine
MemoryForgets between sessions4-tier persistent memory + knowledge graph
DevicesNone (or limited)Wristbands, glasses, smart home, robots, computer
ProactiveNo — waits for promptsYes — watches context and acts
Voice1-2s cloud latencySub-200ms, wake word, interrupt-and-resume
PrivacyData sent to cloudEverything stays local
Open sourceNoYes — Apache 2.0
FERAL focuses on operational orchestration: one runtime for chat, tools, memory, pairing, channels, and device control paths. It is not only a terminal code assistant.

​
Privacy & Security

Choose Anywhere during setup. FERAL tries to enable remote access automatically. If setup reports a tunnel error, run:
feral access remote-up
This enables remote pairing through Tailscale Funnel. Check status with:
feral access status
Only LLM API calls — and only if you choose a cloud provider (Anthropic, OpenAI, etc.). The text of your query is sent to the provider for inference.Everything else stays local:
  • Health data from wearables
  • Memory and knowledge graph
  • Smart-home commands
  • Screen captures
  • Voice audio (processed locally when using Whisper)
If you use Ollama (local models), nothing leaves your machine at all.
Keys are stored in ~/.feral/credentials.enc, encrypted with ChaCha20-Poly1305 (AEAD) and a key derived from your master passphrase via Argon2id. The derived key is cached in your OS keychain so the vault unlocks transparently. The vault decrypts in memory only while FERAL is running and the raw values are never shown to the LLM — credentials are injected at the HTTP layer at request time. See Configuration for details.
Only if you enable it. Computer-use skills (screen capture, browser automation, file operations) are gated by your autonomy mode — set this in Settings → Autonomy in the WebUI (the picker writes to ~/.feral/settings.json under security.autonomy_mode). In strict mode every file or screen action requires explicit approval; in hybrid (default) destructive or dangerous-tier actions still require approval; in loose everything auto-runs. macOS additionally enforces native TCC permission prompts (Screen Recording, Accessibility) before the brain can start a screen-capture loop.

​
Models & Providers

FERAL supports multiple cloud and local providers. The exact live catalog can change by release and provider API.For current provider/model behavior, check Settings in the running dashboard or the provider docs in this site.
Yes. Use Ollama as your LLM provider with a locally downloaded model:
ollama pull llama3:70b
export FERAL_LLM_PROVIDER=ollama
export FERAL_LLM_MODEL=llama3:70b
feral start
Combine with FERAL_VOICE_PROVIDER=whisper_local for offline voice. All hardware, memory, and smart-home features work offline by default.
Yes. Use the dashboard settings or send a command:
> Switch to Claude Sonnet for this conversation
The brain swaps the active provider while preserving conversation context and memory.

​
Hardware

FERAL ships with a BLE adapter for its reference wristband (PPG-based, streaming HR, SpO2, skin temp). It also integrates with Whoop and Oura Ring via their APIs. Any BLE wearable that exposes standard GATT health services can be adapted. See Wristband.
No. Hardware integrations are optional. FERAL works as a powerful AI assistant on just your computer — with memory, voice, computer-use, and all software integrations. Hardware extends it into the physical world.

​
Development

FERAL is in active development. The core brain, memory system, voice pipeline, and hardware mesh are functional. It is suitable for personal use and development. We don’t recommend it for production deployments serving multiple users — yet.
git clone https://github.com/FERAL-AI/FERAL-AI.git && cd FERAL-AI
cd feral-core && pip install -e ".[llm,dev]"
cd ../feral-client-v2 && npm install && npm run dev
Read the CONTRIBUTING.md for coding standards, PR guidelines, and architecture docs. Issues labeled good first issue are a great starting point.
Apache 2.0. You can use, modify, and distribute FERAL freely, including in commercial products, as long as you include the license notice.
Yes. The Apache 2.0 license explicitly allows commercial use. You can build products, services, or integrations on top of FERAL without restrictions beyond license attribution.