Architecture Decisions

What’s landed

• ADR-0001: Manifest Format Conventions — Markdown body + TOML frontmatter for actions; pure TOML for connectors and project config; JSON for runtime IPC.
• ADR-0002: Connector Model — Connectors are sandboxed, content-addressed binaries; Aileron core ships only primitive capability types.
• ADR-0003: Action Model — Atomic actions copied into the user’s ~/.aileron/actions/ on install; depend on connectors with explicit version + hash + capability subsets; capability enforcement at the action boundary in addition to the connector boundary. v1 is user-level only.
• ADR-0004: Dependency Resolution — Per-scheme FQN-to-fetch-URL mapping (Go modules tag conventions); content-addressed shared store; install/sync/check pipelines; offline-by-default after first install.
• ADR-0005: Sandbox Choice — WASM Component Model is the connector sandbox; runtime mediates credential use so connectors never hold raw credentials. Non-WASM-capable connectors are out of scope for v1.
• ADR-0006: Capability Binding UX — Bindings are explicit user acts; install-time transparency, first-use binding, opt-in pre-binding; bindings are user-local, never project-committable; visible lifecycle commands (list/inspect/setup/rebind/revoke).
• ADR-0007: Install Consent Flow — Install is a single binary decision (install or cancel); no per-capability denial; signature failure is a hard fail; updates show capability diffs; headless mode requires explicit --yes per command.
• ADR-0008: Action Exposure to Agents — MCP is the canonical action-exposure surface under both host launch and v4 sandbox launch (the sandbox-launch revival landed in ADR-0024). The generated HTTPS shim surface was retired in #959 ↗, leaving MCP as the sole container tool surface.
• ADR-0009: User Channel and OOB Approval Surfaces — In-band MCP tool result text describes; out-of-band surfaces decide. The agent is structurally never in the trust path for approvals. v1 MVP ships with the webapp /approvals surface plus CLI prompt fallback; system notifications, biometric, and a hosted Aileron backend are Phase 2.
• ADR-0010: Failure-Handling Policy — Failures are visible and structured; closed-set failure-class taxonomy; idempotency is the default; bounded retry on retriable errors; v1 actions are linear with first-failure-terminates semantics. LLM fallback, conditional compensation, and per-call retry tuning are post-MVP enhancements.
• ADR-0011: Local Credential Vault — Encrypted-at-rest local vault for user credentials. Argon2id KDF from a passphrase derives a key encryption key (KEK); AES-256-GCM envelope encryption protects bindings on disk. KEK held in memory for the runtime session, never persisted. The same vault format runs unchanged when the customer operates the runtime in their own infrastructure (BYOC).
• ADR-0012: Local Daemon Architecture — Aileron runs as one long-lived user-scoped local daemon. CLI commands and aileron launch are thin clients that auto-spawn the daemon and connect over TCP-on-loopback at an ephemeral port advertised via ~/.aileron/daemon.json. Vault unlock, sessions, and audit logs live in the daemon. Cloud deployments are a separate shape.
• ADR-0013: Connector Hub and Trust Distribution — The Hub points to connectors at their canonical github://owner/repo FQNs; it does not host artifacts and does not vet publishers. Keyring v2 ratifies per-publisher (Microsoft model) trust as owner-level grants that coexist with per-repo entries. Daemon owns Hub data; CLI and webapp are thin clients on /v1/hub/*. Sigstore deferred with three accepted limitations.
• ADR-0014: Spawn Sandbox Technology — Per-platform mechanism for confining subprocesses spawned via ADR-0002’s spawn primitive. Linux uses pure-Go namespaces plus Landlock; macOS uses sandbox-exec with a generated SBPL profile; Windows uses job objects plus restricted tokens. Manifest is platform-neutral; runtime translates per OS. Unsupported platforms refuse to spawn with a structured error.
• ADR-0015: Launch Audit Scope — aileron launch is daemon-connection + MCP-registration + gateway-routing. The shell-shim (aileron-sh, aileron.yaml policy, Claude PreToolUse hook) is removed. Aileron audits actions Aileron executes — installs, bindings, gateway requests, action calls — via the ADR-0010 audit store. Commands the agent runs locally are outside Aileron’s audit boundary.
• ADR-0016: Approval-Time Preview Fetch — Proposed. An action manifest’s [approval] block may declare a preview directive naming a read-only op the runtime calls before showing the approval prompt. The preview response is rendered into the prompt and never returned to the agent, so the user sees an authoritative summary of what they are approving instead of agent-supplied (and forgeable) hints. Motivated by non-reversible ops like send-draft whose inputs (an opaque draft_id) reveal nothing about the consequence of approving.
• ADR-0017: Sandbox Composition — Proposed. Sandbox images are composed through .devcontainer/devcontainer.json plus customizations.aileron. Aileron owns a minimal aileron/sandbox-base:<version> runtime substrate; users extend it or provide a BYO image with standard container workflows.
• ADR-0018: v4 Single-Binary Runtime Model — Proposed. v4 keeps one aileron runtime model with multiple modes/helpers. Amended 2026-06-08: the sandbox runtime hosts aileron-mcp as an in-container stdio subprocess per ADR-0024; no second sidecar protocol is introduced.
• ADR-0019: v4 HTTPS Data-Plane Mediation — Proposed. Credentialed calls from the agent container flow through an Aileron HTTPS data plane that injects credentials at the proxy boundary instead of exposing secrets in the container.
• ADR-0020: v4 Connector Specs and Generated HTTPS Shims — Proposed. Connector packages provide machine-readable operation specs. The generated HTTPS shim surface these once rendered was retired in #959 ↗; the spec loading is retained for data-plane operation validation, and MCP is the sole container tool surface (ADR-0024).
• ADR-0021: v4 Shell-Layer Mediation — Withdrawn. Container-only shell mediation was prototyped under #801 ↗ and withdrawn in #952 ↗; container isolation, the HTTPS proxy, and tool-level HITL cover the named risks.
• ADR-0022: v4 Tiered Network Policy — Proposed. The v4 container runtime separates credentialed proxy-mediated traffic, direct uncredentialed egress, and denied private-network traffic.
• ADR-0023: v4 Vault-Centric Encryption Schema — Proposed. v4 stores credentials under vault keys that are wrapped per member, allowing personal and future shared vaults to use the same storage model.
• ADR-0024: Sandbox MCP Parity (Path B1) — Accepted. Sandbox launch revives aileron-mcp as a stdio subprocess of the in-container agent, reached via a read-only host-mounted binary; the daemon is reached over HTTPS via host.docker.internal. Aileron is one MCP server, not an MCP gateway. The dual shim surface this ADR initially kept was retired in #959 ↗; aileron-mcp is the sole container tool surface.
• ADR-0025: Vault-backed Agent Authentication Injection — Accepted. The Agent interface gains an AuthSpec descriptor with Render (vault to in-container bytes/env) and Capture (in-container bytes to vault) bindings. The launcher reaches the vault through a new daemon endpoint, snapshots in-container rotations on clean exit, and seeds the vault via the agent’s own interactive login on first launch. Claude and Codex ship per-agent specs; Codex pre-launch refresh persists rotated tokens before container start.
• ADR-0026: CLI-Capability Units — Accepted. One CLI tool’s complete credential story (acquisition plus sealing) ships as one CLI-capability unit under customizations.aileron.cli on that tool’s devcontainer Feature. The host reads the unit from the resolved image’s devcontainer.metadata OCI label and projects it into the existing capture and proxybinding schemas. gh’s former central gh.yaml and github.yaml defaults were removed; its single key now derives every per-store vault reference once.
• ADR-0027: Flight Plan = Sealed Installable Skill — Accepted. A Flight Plan and an Aileron skill are the same construct at two points in one lifecycle; a skill becomes a Flight Plan at a freeze step that pins image digests, produces a lockfile, binds the execution environment, attaches a per-action trust contract, and signs the result. The execution image is agent-free, and an LLM runs only at a single structurally-enforced seam.

The sequence

The eleven ADRs form a complete architectural ratification of Aileron’s v1, tracked in issue #343 ↗:

1. Manifest Format Conventions — landed (ADR-0001)
2. Connector Model — landed (ADR-0002)
3. Action Model — landed (ADR-0003)
4. Dependency Resolution — landed (ADR-0004)
5. Sandbox Choice — landed (ADR-0005)
6. Capability Binding UX — landed (ADR-0006)
7. Install Consent Flow — landed (ADR-0007)
8. Action Exposure to Agents — landed (ADR-0008)
9. User Channel and OOB Approval Surfaces — landed (ADR-0009)
10. Failure-Handling Policy — landed (ADR-0010)
11. Local Credential Vault — landed (ADR-0011)

Aileron is user-level by construction in v1 — actions live in ~/.aileron/actions/, not in the project’s repo. Project-level shared actions and team-coordination features are post-MVP, deferred until the hosted backend ships. The same vault format runs unchanged when the customer operates the runtime in their own infrastructure (BYOC).

How to read these

• Each ADR is a decision, not a design document. Operational detail is included where it ratifies the decision; broader implementation detail belongs in code and PRs.
• ADRs are editable until the first working MVP ships. Real usage will surface assumptions worth revising; until MVP, an ADR is amended in place when its decision changes. Once MVP ships, this section will switch to the standard immutability convention: superseding decisions land as new ADRs that explicitly cite what they replace.