The part where we stop simplifying.

Install

One command detects your OS on Linux and macOS. On Windows, grab the installer from Releases.

Quick start

1. 1
   Install and open Feral. A short welcome wizard introduces the app - pick a name for yourself and your agent.
2. 2
   Get a model. Local: Models → Browse, pick one, click download - Feral pre-selects the quantization that fits your hardware. Or Cloud (BYOK): Settings → Cloud Keys, paste an API key. Keys are stored locally, never proxied.
3. 3
   Chat - or flip to Agent mode. Agent mode unleashes the sidecar: tool-use, persistent memory, file access, and web research.

Prefer the terminal? feral chat opens a full-screen terminal chat (same sessions, memory and models), feral setup runs the wizard, and feral gateway runs it as a background service.

What's inside

Architecture

One repo, four runtimes, three protocols between them. If you came here to fork it and read the code, this section and the two after it are the map - they mirror ARCHITECTURE.md in the repo, which is the version that gets updated first.

┌───────────────────────────┐   ┌───────────────────────────┐
│  Desktop UI (React/Vite)  │   │  TUI (Go + Bubble Tea)    │
└─────────────┬─────────────┘   └─────────────┬─────────────┘
              │ Tauri IPC                     │ HTTP
┌─────────────┴───────────────────────────────┴─────────────┐
│  Rust host - crates/feral-core                            │
│  ├── desktop: src-tauri/      ├── headless: feral-cli/    │
│  ├── llama.cpp inference engine        (:11435)           │
│  └── OpenAI / Ollama-compatible HTTP API + bearer token   │
└─────────────────────────────┬─────────────────────────────┘
                              │ JSON-lines on stdout
┌─────────────────────────────┴─────────────────────────────┐
│  Sidecar - FeralAgent/  (Bun + TypeScript, one binary)    │
│  └── agent loop · BRSI engine · memory · tools · sandbox  │
└───────────────────────────────────────────────────────────┘

The four runtimes

Five rows, four runtimes: the desktop shell and the headless gateway are two hosts of the same feral-core crate.

The three protocols

API keys never reach React. Tauri commands inject your BYOK keys in Rust before anything is forwarded to the sidecar, so the frontend never holds one. If you are auditing where secrets can leak, start at feral_set_model.

Layer map (L0-L6)

The BRSI stack isn't just conceptual - each layer owns a slice of the tree, with hard contracts between them. The one rule that will get your PR bounced: layers never import sideways. Everything goes through the orchestrators at rsi/sidecar.ts, rsi/engine.ts and rsi/mod.ts. Paths below are relative to FeralAgent/src/ unless they say otherwise.

Full per-file breakdown lives at FeralAgent/src/rsi/README.md. The safety contracts are in docs/invariants.md, and the conceptual grounding in docs/brsi-spec.md.

Where do I add X

Every contributor asks at least one of these in the first hour, so here they are up front.

If you add a file under rsi/ update the layer table in ARCHITECTURE.md and rsi/README.md in the same PR. Drift there is treated as a real bug: the next person reading it - human or agent - will believe the wrong thing.

Agent runtime

Flip the composer toggle to Agent mode and your messages go to the Bun/TypeScript sidecar. It recalls relevant memory, streams tokens live, and loops through tool calls until it has an answer - up to 10 iterations per message (50 for complex multi-step tasks like deep research).

user message
    │
    ▼
[Recall]    inject relevant past memory (FTS5 + semantic facts)
    │
    ▼
[Inference] → stream tokens live to UI
    │
    ├── tool call?  → execute → feed result back → loop
    └── no tool call → final answer, persist to memory, done

Failed web/network tools retry with linear backoff and fall back through the web_search → deep_research → read_webpage chain.

Memory layers

Feral layers several kinds of memory that persist across sessions, from a keyword-searchable log up to a semantic tree that understands what you actually talked about.

Fractal Memory is the standout: a RAPTOR-style hierarchy where raw events sit at the leaves, k-means groups related ones, and the model writes a short summary for each cluster all the way up to a single root. Your query is embedded once and traverses that tree, so Feral recalls the gist of past work, not just exact keyword hits. Classic FTS5 + SQLite stay underneath as the always-on fallback, so memory never breaks even before the tree is built.

Privacy tags: wrap sensitive content in <private>…</private> and it's stripped before any episodic write. The model still sees it during the current turn - only the database never does.

Self-improvement (BRSI)

Feral doesn't just run an agent - it improves the agent, and over time the machinery that does the improving. This is BRSI: Bounded Recursive Self-Improvement, a six-layer stack. Each layer answers to the same contract: a change only ships if it measurably beats the current best (the champion), it runs inside a sandbox with an immutable core, every step is written to a hash-chained audit log, and any regression rolls back automatically.

Bounded by design. The layers switch on progressively, and the deep ones (code, tools, governance, meta) are gated and off by default - Meta Evolution always needs a human. The scorer and the safety bounds are part of the immutable core: the agent can improve almost everything about itself, but never the rules that keep it honest. Nothing is open-ended, and nothing ships that didn't prove it was better.

Built-in tools

A representative slice of the built-in surface (persona and connector builds add more, e.g. capture_lead, schedule_meeting). And with tool_forge the agent writes its own tools too, so the list is never fixed. Every tool declares its permissions at registration; undeclared ones are blocked. Network calls go through an egress proxy (SSRF protection, rate limiting, audit log); file tools honor a hard deny-wall on ~/.feral and ~/.ssh.

Privacy, honestly

• Local models. Inference, conversations, and memory never leave your machine. No background network requests, no telemetry, no analytics - by design.
• Cloud models (BYOK). Your messages go to the provider you configured, when - and only when - you hit send. Feral talks to their API directly with your key; nothing is routed through our servers, because we don't have any.
• Web tools. Agent tools like web_search and deep_research make outbound requests through an egress proxy with SSRF protection, rate limiting, and an audit log.
• Update check. Once per launch, Feral asks GitHub Releases whether a newer version exists - only the version request, no usage data. Turn it off in Settings → General for a fully offline app.

Environment variables

The agent sidecar reads these - capable by default, restrictable by choice. The full table is in the README.

License

Feral is source-available under the Business Source License 1.1 (BSL).

• ✅ Free forever for you - personal use, small businesses (under $2M annual revenue), education, research, self-hosting, modifying, redistributing.
• 🚫 Not free for big enterprise - organizations above the revenue threshold, or anyone offering Feral as a hosted service, need a commercial license.
• 🕓 Becomes fully open source automatically - each version converts to Apache 2.0 four years after its release.