# FERAL

> One local brain for every device you own. Open-source AI that connects to your entire physical and digital world.

## Docs

- [Architecture](https://docs.feral.sh/architecture.md): Layered system design covering the FERAL brain, memory, and device mesh.
- [Discord](https://docs.feral.sh/channels/discord.md): Connect FERAL to a Discord server as a bot with full messaging and voice channel support.
- [Push Notifications](https://docs.feral.sh/channels/push.md): Configure FCM (Android) and APNs (iOS) push notifications so FERAL can reach you on mobile.
- [Slack](https://docs.feral.sh/channels/slack.md): Connect FERAL to your Slack workspace using Socket Mode for real-time messaging.
- [Telegram](https://docs.feral.sh/channels/telegram.md): Connect FERAL to Telegram so you can chat with your brain from any device.
- [Contributing](https://docs.feral.sh/contributing.md): How to set up a development environment and contribute to FERAL.
- [Contributing to Docs](https://docs.feral.sh/contributing-docs.md): How to add, edit, and preview FERAL documentation pages.
- [Deployment & Operations](https://docs.feral.sh/deployment.md): Run FERAL in production with Docker Compose, systemd, reverse proxy, and monitoring.
- [AppSurface sandbox](https://docs.feral.sh/genui/sandbox.md): How third-party GenUI surfaces are isolated inside the FERAL host.
- [Manifest signing](https://docs.feral.sh/genui/signing.md): Sign and verify GenUI app manifests with Ed25519 before installing.
- [Configuration](https://docs.feral.sh/getting-started/configuration.md): Configure FERAL via settings files, environment variables, and the credential vault.
- [First Run](https://docs.feral.sh/getting-started/first-run.md): What actually happens on first launch, including access mode and pairing behavior.
- [Installation](https://docs.feral.sh/getting-started/installation.md): Install FERAL using the one-liner script, a manual git clone, or Docker.
- [Android App](https://docs.feral.sh/guides/android-app.md): Set up, configure, and test the FERAL Node Android app.
- [Autonomy Levels](https://docs.feral.sh/guides/autonomy.md): Control how much freedom the agent has to act without human approval.
- [Browser Automation — Setup & Troubleshooting](https://docs.feral.sh/guides/browser-automation.md)
- [Browser Extension](https://docs.feral.sh/guides/browser-extension.md): Access FERAL from any browser — page context, chat sidebar, voice, and right-click actions
- [Channels](https://docs.feral.sh/guides/channels.md): Bridge Telegram, Slack, Discord, and push notifications into the FERAL session system.
- [Channels — Setup Guide](https://docs.feral.sh/guides/channels-setup.md)
- [Desktop App](https://docs.feral.sh/guides/desktop-app.md): Native desktop app powered by Tauri — global hotkeys, floating window, system tray, always-on access
- [Device Adapters (HUP)](https://docs.feral.sh/guides/devices.md): Connect physical devices to the FERAL mesh using the Hardware Use Protocol.
- [Digital Twin — Guide & Ethics](https://docs.feral.sh/guides/digital-twin.md)
- [Email Watcher](https://docs.feral.sh/guides/email-watcher.md): Let FERAL monitor your inbox — VIP filtering, smart summaries, and automated actions via IMAP
- [Federated Memory Sync](https://docs.feral.sh/guides/federated-sync.md): Peer-to-peer memory replication with TLS mutual auth, mDNS discovery, and static peer fallback
- [Gen-UI (SDUI)](https://docs.feral.sh/guides/genui.md): What Gen-UI means in this repo today, what is stable, and what is still evolving.
- [GUI Computer Use](https://docs.feral.sh/guides/gui-computer-use.md): Let FERAL control your desktop — click, type, scroll, and read the screen
- [Hardware Mesh Protocol](https://docs.feral.sh/guides/hardware.md): WebSocket-based mesh for local device control and telemetry streaming.
- [Home Assistant](https://docs.feral.sh/guides/home-assistant.md): Run FERAL as a Home Assistant add-on — full access to every device, automation, and sensor in your smart home
- [iOS App](https://docs.feral.sh/guides/ios-app.md): Set up, pair, and configure the FERAL Node iOS app.
- [Running FERAL Fully Offline](https://docs.feral.sh/guides/local-models.md): Set up FERAL with local LLM, STT, TTS, and vision — no API keys, no cloud, no internet required.
- [Memory System](https://docs.feral.sh/guides/memory.md): Four-tier memory architecture with hybrid search, wiki compilation, and P2P sync.
- [MQTT Bridge](https://docs.feral.sh/guides/mqtt.md): Connect FERAL to any IoT device via MQTT — smart plugs, sensors, Zigbee2MQTT, Tasmota
- [Observability & Metrics](https://docs.feral.sh/guides/observability.md): Prometheus-compatible metrics and OpenTelemetry export for FERAL
- [Pairing & Access](https://docs.feral.sh/guides/pairing-access.md): Exact user flow for pairing phones over LAN or Anywhere mode, with real error handling.
- [PDF Reader — Troubleshooting](https://docs.feral.sh/guides/pdf.md)
- [Security Model](https://docs.feral.sh/guides/security.md): BlindVault, permission tiers, execution sandboxing, and autonomy gating.
- [Writing Skills](https://docs.feral.sh/guides/skills.md): Teach FERAL new capabilities with JSON manifests, Python plugins, or WASM modules.
- [Smart Home — Troubleshooting](https://docs.feral.sh/guides/smart-home.md)
- [Voice Pipeline](https://docs.feral.sh/guides/voice.md): Three voice paths optimized for different latency, cost, and quality tradeoffs.
- [Voice — Troubleshooting](https://docs.feral.sh/guides/voice-troubleshooting.md)
- [Webhooks](https://docs.feral.sh/guides/webhooks.md): Receive events from any service — GitHub, IFTTT, Zapier, Stripe, and more — via FERAL's webhook API
- [Smart Glasses](https://docs.feral.sh/hardware/glasses.md): Stream video from smart glasses for scene analysis, AR overlays, and hands-free voice interaction.
- [HUP — Hardware Unification Protocol](https://docs.feral.sh/hardware/hup-spec.md): FERAL's public wire contract for hardware. If you can terminate TLS and speak JSON over WebSocket, you can build a FERAL-compatible device.
- [Robots](https://docs.feral.sh/hardware/robots.md): Connect robotic actuators to FERAL via the Python SDK, ROS bridge, or serial/I2C adapters.
- [Smart Home](https://docs.feral.sh/hardware/smart-home.md): Control lights, thermostats, locks, and appliances through Home Assistant or the direct HUP mesh.
- [Wristband](https://docs.feral.sh/hardware/wristband.md): Pair a BLE wristband to stream heart rate, SpO2, skin temperature, and sleep data to the FERAL brain.
- [FAQ](https://docs.feral.sh/help/faq.md): Frequently asked questions about FERAL — what it is, how it works, privacy, models, and contributing.
- [Troubleshooting](https://docs.feral.sh/help/troubleshooting.md): Solutions for common FERAL issues — installation errors, connection problems, and runtime failures.
- [FERAL Overview](https://docs.feral.sh/introduction.md): What FERAL is, what it controls today, and how to get started without guesswork.
- [Marketplace (registry.feral.sh)](https://docs.feral.sh/marketplace/overview.md): Install and publish skills, hardware daemons, MCP servers, channels, LLM providers, memory backends, workflow packs, and agent personas — all Ed25519-signed, GitHub-verified.
- [Tool Genesis](https://docs.feral.sh/marketplace/tool-genesis.md): When FERAL doesn't have a tool for what you need, it builds one on the fly — in the same turn.
- [Sync chaos & recovery](https://docs.feral.sh/memory/chaos.md): What FERAL's federated memory sync survives, what it surfaces, and what is genuinely fatal.
- [Metrics, dashboards & alerts](https://docs.feral.sh/operations/metrics.md): Default Prometheus metrics emitted by the FERAL Brain, the bundled Grafana dashboard, and the alert rules that ship with it. Owned by W13 (FEATURE_STABILITY_ROADMAP §3.1 #4).
- [Soak tests](https://docs.feral.sh/operations/soak.md): Long-duration voice + channel soak harnesses for catching slow leaks, reconnect storms, and rate-limit cascades.
- [Quickstart](https://docs.feral.sh/quickstart.md): Install FERAL from PyPI, run setup, and complete your first pairing without trial and error.
- [A2UI Schema Reference](https://docs.feral.sh/reference/a2ui-schema.md): Wire format for Agent-to-User Interface (GenUI) events
- [REST API](https://docs.feral.sh/reference/api.md): Reference for FERAL's HTTP API — dashboard, skills, memory, identity, hardware, and channels endpoints.
- [CLI Reference](https://docs.feral.sh/reference/cli.md): Complete reference for the feral command-line tool — all subcommands, options, and exit codes.
- [Environment Variables](https://docs.feral.sh/reference/environment.md): Complete reference of every FERAL_* environment variable — LLM keys, feature flags, security, hardware, and more.
- [WebSocket Protocol](https://docs.feral.sh/reference/websocket.md): Reference for FERAL's WebSocket protocols — /v1/session for clients and /v1/node for hardware daemons.
- [Node SDK](https://docs.feral.sh/sdk/node.md): TypeScript client for the FERAL Brain API, plugin helpers, and hardware node class.
- [Python SDK](https://docs.feral.sh/sdk/python.md): Talk to a running FERAL Brain, build plugins, and create hardware device adapters.

## OpenAPI Specs

- [openapi](https://docs.feral.sh/api-reference/openapi.json)