# Flynn > A secure, self-improving agent operating system in a single Go binary. Bring any model, manage local models, point it at a goal, and grant it real authority: every action is sandboxed, governed, and sealed into a verifiable, tamper-evident record an independent party can check. Runs interactive or 24/7, or embed it in your own system. - **Type:** MCP server - **Install:** `agentstack add mcp-ionalpha-flynn` - **Verified:** Pending review - **Seller:** [ionalpha](https://agentstack.voostack.com/s/ionalpha) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [ionalpha](https://github.com/ionalpha) - **Source:** https://github.com/ionalpha/flynn - **Website:** https://flynnhq.com ## Install ```sh agentstack add mcp-ionalpha-flynn ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Flynn A secure, self-improving agent operating system in a single Go binary. Bring your own model, point it at a goal, and grant it real authority, because every action is sandboxed, governed, and sealed into a verifiable, tamper-evident record. --- Flynn is a lightweight agent runtime and operating system written in Go. It runs standalone as a single static binary from a laptop to a $5 VPS, works with any model provider, and stores all of its state locally, so you own it. Four ideas run through everything it does: 1. **It compounds.** A closed learning loop turns each session into durable skills and memory, reinforced by whether the work actually succeeded. 2. **It scales past one task.** A goals-and-missions engine plans, fans out, and governs many agent runs toward a single objective. 3. **It owns its cost.** Per-run token and cost budgets with hard ceilings, plus native support for local open-weight models, keep continuous operation affordable and a runaway spend structurally impossible. 4. **You can trust it with autonomy.** Every action is governed, contained, and sealed into a verifiable, tamper-evident record, so giving it real authority is a decision you can audit, not a gamble. ## Why Flynn - **One binary, no runtime.** No Python, no Node, no virtualenv, no `node_modules`. `curl | sh` drops a single file. Cross-compiles to Windows, macOS, Linux, and ARM, and ships in a container measured in megabytes. - **Bring your own model.** Provider-agnostic across hosted and local models, with a curated open-weight catalog and hardware-fit checks for running fully local. No lock-in. - **Learns from your work.** Captures skills and memory as you go and reinforces them based on real outcomes. - **Orchestrates, does not just chat.** Turns an instruction into a plan and fans it out into concurrent, governed runs under a shared budget. - **Extends itself.** Writes its own skills, validates them in a sandbox, and puts them to work without a redeploy. - **Useful inside and outside a larger system.** Run it on its own, or import it as a Go module and embed it in your own application. ## Install One line, no toolchain needed. The script downloads a prebuilt binary for your OS and architecture and verifies its checksum before installing. ```sh # Linux and macOS curl -fsSL https://raw.githubusercontent.com/ionalpha/flynn/main/install.sh | sh ``` ```powershell # Windows (PowerShell) irm https://raw.githubusercontent.com/ionalpha/flynn/main/install.ps1 | iex ``` Pin a version with `FLYNN_VERSION` (for example `FLYNN_VERSION=v0.1.0`) or change the install directory with `FLYNN_INSTALL_DIR`. That is the last time you need the script. From then on the binary maintains itself: ```sh flynn version list # what releases exist flynn upgrade # install the newest one ``` `flynn upgrade` verifies a release before installing it, with no cosign, no gh, and no trust placed in the network: it checks the signature against a Sigstore trust root compiled into the binary, requires the signing identity to be this repository's release workflow on a version tag, requires the signature to be present in the public Rekor transparency log, and only then downloads the archive, pinned to the digest the signed provenance names. It refuses downgrades, will not trample a package-manager install, and keeps the old binary if the new one does not run. See [docs/UPGRADE.md](docs/UPGRADE.md). Prefer another method? Each option below installs the same release. Docker (GHCR or Docker Hub) Multi-architecture images (amd64, arm64) are published on each release. Mount a volume for the durable state (SQLite store, credential vault, learned skills) so it survives container replacement, and pass a model key: ```sh docker run -v flynn-data:/data \ -e ANTHROPIC_API_KEY=your-key \ ghcr.io/ionalpha/flynn:latest ``` The same image is on Docker Hub as `ionalpha/flynn:latest`. Pin a version by tag (`:0.1.0`) instead of `latest`. The API binds loopback inside the container on purpose; add a channel (for example `-e TELEGRAM_BOT_TOKEN=...`) to reach the agent, or see [`deploy/README.md`](deploy/README.md) for remote access and hardening. Every published manifest is keyless-signed with cosign and can be verified: ```sh cosign verify ghcr.io/ionalpha/flynn:latest \ --certificate-identity-regexp 'https://github.com/ionalpha/flynn/.*' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com ``` Linux packages (deb, rpm, apk) Native packages for Debian/Ubuntu, Fedora/RHEL, and Alpine are attached to every [release](https://github.com/ionalpha/flynn/releases). Download the one for your distribution and architecture, then: ```sh sudo dpkg -i flynn_*_linux_amd64.deb # Debian, Ubuntu sudo rpm -i flynn_*_linux_amd64.rpm # Fedora, RHEL sudo apk add --allow-untrusted flynn_*_linux_amd64.apk # Alpine ``` Go toolchain (build from source) Needs Go 1.26+: ```sh go install github.com/ionalpha/flynn/cmd/flynn@latest ``` Manual download and verify Prebuilt binaries for Windows, macOS, Linux, and ARM are attached to every [release](https://github.com/ionalpha/flynn/releases) alongside a `checksums.txt`. The checksum file is signed with cosign; verify it before trusting a binary: ```sh cosign verify-blob checksums.txt \ --signature checksums.txt.sig \ --certificate checksums.txt.pem \ --certificate-identity-regexp 'https://github.com/ionalpha/flynn/.*' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com sha256sum -c checksums.txt --ignore-missing ``` ## Quick start ```sh flynn --model anthropic:claude-opus-4-8 # start an interactive session flynn --version ``` Store your model API key once. It is encrypted at rest in your OS keychain (or a passphrase-sealed file where there is no keychain) and revealed only to call the model, never written to a prompt, a log, or a command's environment: ```sh flynn auth set openai # prompts for the key without echoing it ``` Give it a goal and let it work the problem and report back: ```sh flynn goal "audit the repo for security issues and open a PR with the fixes" ``` Run it as a long-lived service that answers messages from your chat channels: ```sh flynn serve # answers Telegram and Signal messages, triaged and driven as goals ``` Building from source: `go build -o flynn ./cmd/flynn`. ## Failure modes designed out A handful of bugs recur across agent implementations: session and message state drifting out of sync or going missing, context compaction overwriting earlier work, a config change quietly disabling a safety check, a misclassified provider error retrying into a long hang, and crashes that loop on restart. Flynn is built so that several of these are hard to express in the first place, not because they are caught after the fact, but because the structure does not contain the boundary they live in. - **One source of truth for state.** Sessions, messages, skills, and memory are projections of a single append-only event log, so there is no second copy to drift from and nothing is overwritten in place. - **No silent loss.** Every change is an ordered, acknowledged, replayable event; a failed write is a retryable event rather than a dropped one, and compaction is a view over the log, so the original is always recoverable. - **Deny by default.** Tools are scoped by capability rather than by a blocklist, so a config change can remove access but never accidentally grant it. - **Typed failures.** Errors carry a class set at the adapter boundary, so a permanent failure such as a bad key or an unavailable model stops quickly instead of retrying into a hang. - **One static binary.** No language runtime and no native add-ons, which removes the install-time and crash-on-startup failure modes that come with them. This is the project's main bet: the discipline that makes autonomy safe to grant, an event-sourced, governed, replayable foundation, is the same discipline that keeps the ordinary failure modes from arising. The foundation comes first, and every capability below is built as a typed resource on top of it. ## Features The sections below describe Flynn's capabilities by area. For what runs today versus what is in progress or planned, see [Status and roadmap](#status-and-roadmap). ### Agents and capabilities Flynn runs as an **agent**: a system prompt, the model and loop it runs on, and a set of **capabilities** that map to the concrete tools the agent is allowed to use, so it only ever has the surface it needs. Agents are versioned resources and compose (one can extend another), and a delegated sub-agent is granted a subset of its parent's authority. By default Flynn runs a general-purpose agent. ### Goals, missions, and orchestration - **Goals and missions.** A *goal* is one objective with a verifiable end-state. A *mission* is long-horizon work that owns a tree of sub-goals and outlives any single session. - **A goal tree.** A goal owns its sub-goals, and a mission tracks that tree as it fans out and converges, so long-horizon work is structured, not a flat list. - **Plan and dispatch.** An instruction becomes a plan; the dispatcher fans it out into concurrent governed runs, each bounded by the shared budget. - **A governor.** Every run is bounded by a shared budget pool (tokens and cost), an autonomy level, and an approval policy. - **A mission event spine.** Every decision, tool call, message, approval, and checkpoint is an ordered, immutable event that replays for a full audit trail and rolls up into live progress. - **Isolation.** Runs execute in a sandbox, so parallel agents never collide. - **Declarative and self-healing.** You declare a goal's desired end-state; a reconciler drives toward it and converges again after a failure or restart, instead of losing the thread mid-task. ### The interactive session The terminal is not a chat box bolted onto an API. The session is the typed event spine rendered live, so you watch the agent work with the governance and record layers in view rather than hidden behind it. - **The governed stream, on screen.** Governance decisions and record events are projected onto the conversation as they happen. A governance overlay (Ctrl+O) shows the run's current posture: what was admitted, what was denied, and why. - **Seal and verify without leaving the shell.** `/seal` seals the current run and `/verify` checks it, with a record badge showing the run's verifiable state inline. - **Replay in place.** `/replay` re-renders a recorded run from its events, and run pickers badge each run with its record state. - **Built for real terminals.** An alternate-screen fallback for hostile emulators, cross-emulator key handling (`modifyOtherKeys`), image paste into the composer, and `@`-completion ranked by frecency. ### The learning loop - **Skills from experience.** After complex work, the agent writes reusable skills and improves them as it reuses them. - **Memory.** Durable facts about you and your work, prefetched into context and synced after each turn. - **A curator.** An outcome-driven pass decays and archives skills that stop working, so the library stays sharp instead of sprawling. Nothing is ever silently deleted. - **Reinforced by outcomes.** Skills and memory are strengthened or decayed by real signals (tests passing, a task accepted, no correction on the next turn), so the agent learns what works, not what it merely tried. - **Provenance.** Every captured skill or memory is versioned and attributable, so you can see which version produced a result, and roll it back. ### Self-extension The agent treats its own capabilities as data it can author. - **Integrations are specs, not code.** A new API integration is a catalog entry plus a declarative endpoint contract, executed by one generic engine with auth, rate limits, and safety built in. - **It writes its own skills.** When it hits a gap, the agent can author a new skill, validate it in a sandbox, and put it to work without a redeploy or a recompile. - **Extensions run out of process.** An extension is a separate binary that speaks MCP, launched confined, so a third-party tool never shares the agent's address space. The client is strictly one-directional: an extension answers calls, it cannot drive the agent. `flynn extensions dev ` links a locally built one for authoring, and `flynn extensions call` runs a single tool confined. - **Portable.** Every skill is a versioned, attributable resource you can export and move between machines. ### Code review - **A formal verdict, not a comment.** `flynn review /#` reviews a pull request under the reviewer archetype: one pass over every changed file, then a sweep for what the per-file passes missed. Each finding lands on the line it concerns, and the verdict links to it. - **Findings that persist across pushes.** A standing finding is handed back to the reviewer on the next run so it is rechecked rather than repeated, and a conversation resolves once the finding it raised is gone. - **Authority is bounded.** Approval is gated behind an explicit `--approve --as`; by default the reviewer can request changes and comment but never approve. The command exits non-zero when it requests changes, so it drops straight into a pipeline. ### External agent backends Flynn can drive another coding agent as the model behind a run (`--model claude` or `--model codex`) while keeping its own governance around it. The external harness is locked to Flynn's bridge: its native tool surface is denied, and only the tools Flynn bridges to it are callable, so every action still passes the dispatch waist and lands in the run's record as attested events. On platforms without a governed-egress leg the command refuses and says so rather than running the child unconfined. Either backend drives a one-shot goal, a pull-request review, or an interactive session: ```bash flynn --model claude # chat, turn by turn, through the CLI flynn --model codex:gpt-5-codex goal "fix the flaky test" flynn review owner/repo#123 --model claude ``` In a session the conversation belongs to the CLI: each turn continues the conversation the harness itself holds, so it answers with the context of the turns before it. The run is still one durable, sealed record on Flynn's side. `/model claude:` retargets the model the CLI drives from the next turn on, without disturbing that conversation. Switching to a different harness mid-run is refused: a record declares the one harness that drove it, so the swap belongs in a new session. A session driven by an external agent does not learn back into Flynn's skills and memory, and `/compact` does not apply to it: the harness holds the conversation and manages its own context. `flynn serve` and `flynn watch` do not take an external backend, because a server's independent requests have no single conversation to continue. ### Channels and computer use - **Real tools on a real machine.** A sandboxed, path-confined toolset for the terminal and filesystem: run commands, read, edit, glob, and grep, each admitted at the dispatch waist against a capability grant. - **Lives where you do.** Run it from the terminal, or as a service (`flynn serve`) that answers Telegram and Signal messages, each triaged and driven as a goal. Wider reach (Discord, Slack, voice, a built-in browser, desktop GUI, and mobile control) is on the [roadmap](#status-and-roadmap). ### Ambient triggers - **React to markers.** A `flynn watch` mode picks up inbound `ai!` / `ai?` markers in your files and turns them into governed goals, so work can start without a prompt at the terminal. Autonomy that forms its own goals from monitored signals is on the [roadmap](#status-and-roadmap). ### Cost control - **Hard budgets.** The gover … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ionalpha](https://github.com/ionalpha) - **Source:** [ionalpha/flynn](https://github.com/ionalpha/flynn) - **License:** Apache-2.0 - **Homepage:** https://flynnhq.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ionalpha-flynn - Seller: https://agentstack.voostack.com/s/ionalpha - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.