spawn

A capability-secured orchestration engine for fleets of AI coding agents.

spawn runs a hierarchy of long-lived AI agent sessions — a commander that sees the whole fleet, managers that own a project, and workers that do the deep work — across terminal-backed sessions on one or many hosts. It gives those agents a typed, deny-by-default control plane to coordinate with each other: dispatch work, nudge a stalled peer, hand a task off, capture another session's screen, and report results up the chain — all mediated by a single authorization gate and recorded in a tamper-evident audit log.

This repository is a curated, source-available snapshot of the engine's core, published as an architecture showcase. It is a subset of a larger internal system; deployment glue, host-specific configuration, and a proprietary secure-messaging bridge are intentionally omitted. See Scope below.

---

Why it exists

Coordinating more than one autonomous coding agent quickly runs into the same problems a small operations team has: who is allowed to do what, to which project; how does a stalled worker get unblocked; how do you prove after the fact what an agent was authorized to do and actually did. spawn answers those with a small, pure, testable core rather than ad-hoc scripting.

The design goals, in order:

1. Deny-by-default security. No agent can act outside its granted authority, and the top tier of actions requires an explicit, out-of-band operator grant that even the commander cannot self-issue.
2. Verified identity. A principal's authority derives from verified identity (the OS uid/session locally; a forward-auth session remotely) — never from anything the caller can claim in a request.
3. Tamper-evidence. Every authorization decision is appended to a per-principal SHA-256 hash chain, so the record cannot be silently edited or reordered.
4. Portability. The core is pure Rust over ~/.claude state and a pluggable session backend (a native PTY implementation and a tmux implementation). No host-specific assumption lives outside the backend seam.

---

Architecture

1. The capability security spine (spawn-core/src/security_spine.rs)

The heart of the system is a small Policy Enforcement Point: a pure function authorize(principal, verb, tenant, project) -> Allow | Deny. It is deny-by-default — a request must clear every check or it is refused.

• Verb tiers. Actions are classified on a total order of sensitivity: Read < Steer < Spawn < Kill < OperatorOk. A role grants authority up to a maximum tier.
• Roles. Commander (up to the operator-OK tier), Manager (up to Spawn), Worker (up to Steer). A worker can steer a peer but never spawn or kill one.
• Scope. A principal carries a tenant and a project scope (All or an explicit set); a decision checks tenant match and project membership.
• The operator-OK floor. The most sensitive tier is unreachable without an explicit operator_ok grant that is minted out-of-band. Even a commander is denied an operator-OK action without it.
• Verified identity. Principals are resolved from authentication at the boundary — an IdentitySource trait with an OS-uid implementation for the local case and a forward-auth implementation for the remote case. Group membership maps to a role; identity is never read from a request payload, header, or working directory.

Two further controls harden the spine:

• Manifest partitioning — a "floor" set of controls that a customizable config can never address or weaken.
• Integrity gate — verify-before-enforce of the control-root files against pinned SHA-256 hashes, failing closed on tamper or a missing file.

2. Tamper-evident audit chain (security_spine.rs, section 4)

Every gate decision becomes an AuditRecord whose hash is sha256(prev_hash | canonical fields). Because each record commits to its predecessor, altering any field or reordering the chain breaks every subsequent hash — the log is tamper-evident by construction, per principal.

3. The dispatch hierarchy (dispatch.rs, commander.rs, manager.rs, fleet.rs)

The commander/manager/worker model is expressed as data and pure predicates — can_dispatch, can_deploy_prod, role resolution, fleet rollup — so the routing rules are unit-testable without spinning up a single real session. Dispatch, hand-off, and reporting flow up and down the tree through this layer.

4. The MCP server (spawn-mcp)

A stdio Model Context Protocol server gives an AI agent a typed interface to the fleet instead of screen-scraping a terminal. Each tool is a thin shell over a pure, separately-tested core function. The exposed surface includes:

Tool	Purpose
spawn_status / spawn_team	enumerate sessions and drain their structured reports
spawn_dispatch	send work to a project session (gated by the capability model)
spawn_nudge / spawn_push	prompt a live or stalled session
spawn_handoff / spawn_reply	pass a task between sessions, reply on a correlation token
spawn_capture	read another session's scrollback
spawn_idle / spawn_watchdog	liveness and self-healing signals
spawn_halt / spawn_kill	stop work / tear a session down

The server can serve a port-filtered subset of tools per instance, so a remote or lower-trust caller sees only the tools it is allowed to invoke.

5. The session backend seam (spawn-core/src/backend/)

SessionBackend is the trait that abstracts "a named, long-lived terminal session you can write keystrokes to and read scrollback from." Two implementations ship: a native PTY backend built on portable-pty + vte (portable across Unix PTYs and Windows ConPTY), and a tmux backend. Everything above the seam is backend-agnostic.

6. Frontends

• spawn-cli — the command-line frontend over the core.
• spawn-tui — a ratatui cockpit: a live grid of sessions with fuzzy switching, rendered from the same core.

---

Workspace layout

crates/
  spawn-core/   the reusable engine: capability spine, audit chain, dispatch
                hierarchy, session backends, ledger/handoff/report coordination
  spawn-cli/    command-line frontend
  spawn-mcp/    stdio MCP server exposing the typed fleet-control tools
  spawn-tui/    ratatui terminal cockpit

The core carries 340+ unit tests (368 across the workspace), most of them exercising the pure authorization, audit, dispatch, and coordination logic directly.

Build

cargo build --workspace
cargo test  --workspace

Scope of this snapshot

This is a deliberately partial, source-available publication meant to show the engineering, not to be a drop-in deployment:

• Two internal crates are omitted: a remote control-plane listener and a proprietary end-to-end-encrypted messaging bridge (the latter is separately licensed and links third-party GPL code).
• Deployment scripts, CI, container definitions, the private project registry, and host/network configuration are excluded.
• Example identifiers in tests and comments are generic placeholders.

License

AGPL-3.0-only — see LICENSE for the full text.

A commercial license is available for use outside the AGPL-3.0 terms — contact Info@Seglamater.com. (Formal commercial-license terms are being finalized.)

Versions previously published under the Business Source License 1.1 remain available under BSL-1.1.

Copyright © 2026 Seglamater Services LLC.