Flynn

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.

1. It scales past one task. A goals-and-missions engine plans, fans out, and

governs many agent runs toward a single objective.

1. 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.

1. 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.

# Linux and macOS
curl -fsSL https://raw.githubusercontent.com/ionalpha/flynn/main/install.sh | sh

# 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:

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:

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:

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. Download the one for your distribution and architecture, then:

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+:

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 alongside a checksums.txt. The checksum file is signed with cosign; verify it before trusting a binary:

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

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:

flynn auth set openai     # prompts for the key without echoing it

Give it a goal and let it work the problem and report back:

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:

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:

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
• Source: ionalpha/flynn
• License: Apache-2.0
• Homepage: https://flynnhq.com

Install and usage instructions live in the source repository linked above.