One brain. Every device. Your entire life.
The open-source AI that connects to everything you own — wristband, glasses, home, computer, phone, robots — learns your baseline, and runs things the way you would. Locally. Privately. No cloud.
The Idea · What It Does · Get Started · Demos · Architecture · Contributing
OpenAI built a chatbot. Apple built Siri. Google built an ad machine. Meta open-sourced some weights and called it a day.
None of them built an AI that connects to your wristband, your smart glasses, your thermostat, your robot arm, your computer, and your phone — learns your routines, builds your baseline, and proactively manages your physical and digital world. All locally. All privately.
We did. And we open-sourced all of it.
The Idea
FERAL is a Spatial Agentic OS — a single AI brain for your entire physical and digital life. It connects to every device, every app, every sensor you own. It learns your daily baseline across all of them. And it proactively manages hardware, software, health data, and your environment through natural language and intent.
flowchart TD
CAL["Calendar\nEmail\nSlack\nSpotify\nNotion"] --- BRAIN
HEALTH["Whoop\nOura Ring\nWristband\nHR · SpO2 · Sleep"] --- BRAIN
HOME["Smart Lights\nThermostat\nAppliances\nLocks"] --- BRAIN
GLASSES["Smart Glasses\nVideo Stream\nAR Overlay"] --- BRAIN
BRAIN["FERAL Brain\n---\nMemory · Identity\nAutonomy · Voice\nProactive Intelligence"]
BRAIN --- COMPUTER["Your Computer\nScreen · Browser\nFiles · Terminal"]
BRAIN --- PHONE["Your Phone\nPush · Location\nCamera"]
BRAIN --- ROBOTS["Robots\nROS · Serial\nI2C · Actuators"]
BRAIN --- VOICE["Voice\nWake Word\n3 Providers\nSub-200ms"]
It talks to every device — wristbands, smart glasses, home appliances, robots, your computer, your phone. It integrates with every app — calendar, email, Telegram, Slack, Spotify, Notion. It builds a living model of your routines and health through persistent memory. And it acts based on the level of autonomy you choose:
| Mode | Behavior |
|---|---|
| Strict | Every action requires your explicit approval via a confirmation card |
| Hybrid | Safe actions auto-execute; risky ones ask first |
| Loose | Full autopilot — FERAL acts, you review the log |
What It Does
Comparison
| Dimension | Big AI (OpenAI, Apple, Google) | OpenClaw | FERAL |
|---|---|---|---|
| Where it runs | Their servers | Your terminal | Your entire device ecosystem |
| Memory | Forgets between sessions | Plugin-based | 4-tier + knowledge graph + P2P sync |
| Voice | 2s latency, cloud-only | Extension-based | Sub-200ms, wake word, 3 providers |
| Health monitoring | No | No | Real-time biometrics from wristband |
| Smart home | Cloud API roundtrip | No | Direct local mesh, no cloud |
| Proactive intelligence | No | No | Rule + LLM hybrid with coaching |
| Identity / learning | No | Workspace files | SOUL.md + USER.md + auto-learning |
| Autonomy levels | No | No | Strict / Hybrid / Loose |
| GenUI | No | Canvas/A2UI | Full SDUI generation engine |
| Hardware protocol | No | Generic nodes | Dedicated HUP + mesh |
| Open source | Weights only | Yes | Yes — brain, client, mobile, SDK, desktop |
Get Started
One-liner (installs everything, creates a virtual env):
curl -sSL https://raw.githubusercontent.com/FERAL-AI/FERAL-AI/main/scripts/install.sh | bash
After install, activate and run:
source ~/.feral-env/bin/activate
feral start
Or clone manually:
git clone https://github.com/FERAL-AI/FERAL-AI.git && cd FERAL-AI
make install # or: cd feral-core && pip install -e ".[llm]"
feral start
Brain starts, UI opens, voice activates. No API key required for local models (Ollama auto-detected).
Want cloud LLM instead?
export ANTHROPIC_API_KEY=sk-... # or OPENAI_API_KEY, or OPENROUTER_API_KEY
feral start
Demos
☀️ The Morning Routine
You wake up. FERAL already knows your sleep data from the wristband. It briefs you: calendar, weather, overnight emails — unprompted. You say "lights to morning mode" and your Philips Hue shifts warm. All voice. All local context.
feral demo --scenario morning
💻 The Developer Flow
You're deep in VS Code. FERAL watches your screen, notices you've been stuck on the same error for 20 minutes. It interrupts: "I see a null pointer on line 47 — the API response changed shape after the deploy at 3pm. Want me to fix it?" It knows because it has your screen context AND your git history in memory.
feral demo --scenario developer
🔗 The Mesh
Phone, wristband, smart glasses, desktop — all connected. You start a conversation on your phone walking to work. Sit down at your desk. FERAL picks up exactly where you left off, now with your full screen context. Your heart rate spikes during a meeting — it dims the lights and queues a breathing exercise. No cloud. No subscription. Just your devices, talking to each other.
feral demo --scenario mesh
🤖 Ask Your Digital Twin
You're considering a job offer. Instead of pro/con lists, you ask: "What would I think about this?" FERAL's digital twin — built from your memory, preferences, and decision patterns — reasons through it as you would.
feral demo --scenario twin
Architecture
flowchart TB
subgraph brain [FERAL Brain — feral-core]
LLM["LLM Orchestrator\n9 providers"]
MEM["Memory Store\n4-tier + KG"]
PRO["Proactive Engine\nrule + LLM hybrid"]
VOI["Voice Pipeline\nOpenAI RT / Gemini / Whisper"]
SEC["Security\nvault + sandbox + approvals"]
SKL["Skills\n17 manifests + WASM"]
GEN["GenUI Engine\nSDUI generation"]
INT["Integrations\nCalendar · Email · Health\nSpotify · Notion · Home"]
end
subgraph clients [Clients]
WEB["Web Dashboard\nReact · The Orb · SDUI"]
DSK["Desktop App\nTauri"]
PHN["Phone\niOS / Android bridges"]
end
subgraph hardware [Hardware Mesh]
WRI["Wristband\nBLE · HR · SpO2"]
GLS["Smart Glasses\nvideo stream"]
HOM["Smart Home\nHue · HA · appliances"]
end
brain <-->|"WebSocket\n/v1/session"| clients
brain <-->|"HUP Protocol\n/v1/node"| hardware
Brain (feral-core): Python. FastAPI + WebSocket. LLM orchestration, tool execution, memory, proactive intelligence, voice pipeline, hardware mesh coordination.
Client (feral-client): React. Server-Driven UI. The Orb. Command palette. Ambient context strip. Timeline view. Pure renderer — the brain decides what to show.
Nodes (feral-nodes): Hardware bridges that connect physical devices to the brain via the mesh protocol. Wristband streams biometrics. Glasses stream video. Smart home controls actuators.
The Stack
feral/
├── feral-core/ # Brain: Python, FastAPI, LLM orchestration
│ ├── agents/ # Orchestrator, proactive engine, digital twin, scheduler
│ ├── memory/ # Episodic, semantic, knowledge graph, vector search, sync
│ ├── voice/ # Wake word, OpenAI Realtime, Gemini Live, Whisper path
│ ├── hardware/ # HUP mesh protocol, device adapters
│ ├── integrations/ # Calendar, email, health, Spotify, Notion, Home Assistant
│ ├── skills/ # Plugin system, 17 manifests, WASM sandbox, marketplace
│ ├── perception/ # Screen capture, audio pipeline, sensor fusion, geofencing
│ ├── channels/ # Telegram, Discord, Slack, WhatsApp, push notifications
│ ├── genui/ # Server-driven UI generation + provider system
│ └── security/ # Vault, sandbox, permissions, approval gates
├── feral-client/ # Web UI: React, The Orb, SDUI renderer, Timeline, Ambient
├── feral-nodes/ # Hardware bridges: iOS, Android, phone, Python SDK
├── desktop/ # Desktop app: Tauri (Rust + Web)
├── sdk/ # Developer SDK: Python + Node.js
└── docs/ # Documentation site (Docusaurus)
Contributing
git clone https://github.com/FERAL-AI/FERAL-AI.git && cd FERAL-AI
cd feral-core && pip install -e ".[llm,dev]"
cd ../feral-client && npm install && npm run dev
See CONTRIBUTING.md for the full guide.
Why "FERAL"?
Feral: adjective — (of an animal) in a wild state, especially after escape from captivity.
AI was supposed to be personal. To serve you. Instead, it got captured — locked behind subscriptions, harvested for training data, chained to someone else's cloud. Every "personal AI" on the market today is personal in name only.
FERAL is what happens when you break AI out of captivity and let it run wild on your own devices. It knows your heartbeat. It sees your screen. It controls your home. It remembers everything. And it never phones home.
Not because we're idealists. Because that's how it should have worked from the start.
AI off the leash.
Apache 2.0 · Made with spite and good intentions
1 maintainer
Metadata
1 maintainer
Release files for feral-ai 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| feral_ai-1.2.0.tar.gz | 691.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| feral_ai-1.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / feral_ai-1.2.0.tar.gz
| Download URL | feral_ai-1.2.0.tar.gz |
|---|---|
| Size | 691.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2dcf64bc934eb20a482d84e3e1f33da6959243d17cbd95e7aba90cdd77232de2
|
|
BLAKE2b-256 checksum How to use checksums |
970dd64120c7ed0aa03370e5b442d5f2fdab2bcc77e632a115f5ec9830a9aaf6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 13, 2026.
Transparency logRelease files / feral_ai-1.2.0-py3-none-any.whl
| Download URL | feral_ai-1.2.0-py3-none-any.whl |
|---|---|
| Size | 774.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
22991d2681ad0c8ec3e259026800eeac037935467c6f698f2f7fd1c501be2ebd
|
|
BLAKE2b-256 checksum How to use checksums |
ecfb54c64f67fd8ce7ef465634dffdaa1e0e52c4d0b688206af405f9827531f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 13, 2026.
Transparency log
