AileronControlPlane

Binary Architecture

An Aileron install currently ships multiple cooperating binaries, but the v4 runtime model treats aileron as the product boundary. aileron-mcp is the MCP adapter both host launch and v4 sandbox launch register with the agent; under sandbox launch it runs as a stdio subprocess of the in-container agent, reached via a read-only host-mount (see ADR-0018 and ADR-0024).

The two binaries

BinarySourceTrust boundaryCalled by
aileroncmd/aileron ↗CLI plus user-scoped local daemon (per ADR-0012). The vault, sessions, audit log, connector store, binding store, sandbox launch, and future v4 data-plane modes live behind this runtime boundary.The user, launch flows, the in-container aileron-mcp tool surface, and future runtime helpers.
aileron-mcpcmd/aileron-mcp ↗MCP adapter for both host launch and v4 sandbox launch. Translates an MCP tools/call request from the agent host into an HTTP POST to the local daemon’s /v1/actions/{name}/run. Under sandbox launch it runs in-container as a stdio subprocess of the agent (ADR-0024).Host-launched and sandbox-launched MCP-aware agent hosts.

How they cooperate

┌─────────────────────────────┐
│  Agent host (Claude Code,   │
│  Codex CLI, Goose,          │
│  OpenCode, …)               │
└──────────┬──────────────────┘
           │
           │ MCP tools/call
           │ + LLM gateway
           ▼
   ┌────────────────┐
   │  aileron-mcp   │  (host OR in sandbox container)
   └───────┬────────┘
           │
           │ HTTP /v1/actions
           ▼
        ┌─────────────────────────┐
        │   aileron daemon        │
        │  (cmd/aileron)          │
        │  vault, sessions,       │
        │  audit, connector       │
        │  store, executor,       │
        │  LLM gateway            │
        └─────────────────────────┘

The daemon is the trust pivot. Vault unlock happens in its process; nothing outside it ever sees the master key. The other binaries are thin clients that hand requests to the daemon and surface the daemon’s structured responses back to whoever called them.

Per ADR-0015, Aileron’s host-launch audit boundary is the actions Aileron executes (connector installs, action invocations, binding lifecycle, gateway-routed LLM requests). Commands the host-launched agent runs locally through its own exec tool — git, go test, rm — are outside this boundary. Container-only shell mediation was prototyped under #801 ↗ and withdrawn in #952 ↗; see ADR-0021 (Withdrawn).

What runs where

  • aileron launch <agent> with --sandbox=off starts the agent host as a subprocess and wires aileron-mcp into its MCP transport (per ADR-0012). The daemon auto-spawns on first call and stays running as long as a session is active.
  • aileron launch --sandbox=auto|docker <agent> prepares the selected sandbox image, validates it, and runs the agent command in a container. It bind-mounts the host-built aileron-mcp at /usr/local/bin/aileron-mcp:ro and registers it with the in-container agent (ADR-0024), and injects AILERON_API_URL and session metadata. aileron-mcp is the sole in-container tool surface.
  • aileron daemon start|stop|status controls the daemon directly. Useful for diagnostics, rare in normal use.
  • aileron-mcp can be installed standalone with task mcp:setup when an agent host needs the MCP server outside an aileron launch session.

Versions are coupled

All shipped binaries are built from the same repo at the same commit. The release pipeline produces a matched set; a task build builds them together. Mismatched versions (e.g., a newer aileron-mcp talking to an older daemon) are not supported, because the daemon’s HTTP API is the contract and we have not committed to compatibility across versions yet.

This is a pre-MVP simplification. Per ADR-0012’s versioning section, a stable wire protocol is a post-MVP concern; until then, ship the binaries together.

See also