Aileron v4

What this makes possible

Concrete scenarios teams and organizations can run on Aileron:

• An agent reads a Slack support thread, opens a Linear bug ticket, runs a GitHub Actions deploy of the fix, and updates the affected customer’s Stripe record. The deploy and the Stripe write require human approval. The full trail is auditable to a specific engineer.
• A new engineer joins, gets an Aileron account, and runs their first session with the team’s curated connectors already provisioned (Linear, Slack, internal services). Credentials live in the team vault, rotated centrally. No per-laptop setup.
• The platform team rolls out an internal-tools agent across engineering, support, and sales. Every team’s agent uses the same Aileron substrate, the same policy framework, the same audit destination. One operating model across the company, not one custom integration per team.
• A production-touching agent runs overnight with confidence that the agent cannot bypass approval gates, exfiltrate credentials, or escape its container’s blast radius. Engineers wake up to a queue of completed actions and any rejected pending requests.
• Leadership asks for AI spend visibility across the company. Aileron shows LLM-token consumption per agent, per team, per project, alongside which actions ran, which were approved, and which upstream systems were touched.
• A compliance review for AI-mediated production access points at integrated action-level audit, approval workflows, RBAC, and BYOC credential isolation where the customer operates the runtime and Aileron never sees credentials. The audit shape matches what SOC 2 or HIPAA controls already require.
• The platform team migrates from “agents on developer laptops” to “agents as a managed platform service” without rewriting any agent code. Same connectors, same policy, same audit. The deployment topology shifts; the architecture does not.

What teams and organizations gain

Capabilities that compound across every agent and every team:

• One substrate for every agent. Whatever model (Claude, GPT, Gemini, open-weights), whatever framework, whatever team: every agent runs through the same Aileron runtime, with the same policy, approvals, audit, and credential boundary.
• Identity at the agentic layer. Per-user authentication, per-team vaults, RBAC on credentials and actions. Every agentic action is attributed to a human, not to “the agent.”
• Action-level policy declared per connector and enforced by the runtime. Idempotency, approval requirements, and audit shape are uniform across every invocation.
• Human-in-the-loop approval as a first-class primitive. Irreversible actions pause; approvers grant or reject out of band; agents continue.
• Action-attributed audit with user identity, parsed arguments, approval decision, and outcome. The audit trail compliance review actually uses.
• A curated connector ecosystem. Installing a connector package gives the organization a typed action surface with policy declared. New systems light up across all teams at once.
• Fleet visibility. Aileron is the single point every agentic action passes through. That makes it the natural place to report LLM spend, tool usage, approval latency, and error rates across teams, agents, and projects.
• Bounded agent runtime. Container-level isolation, a credential boundary the agent cannot reach behind, tool-level approval gating, and restricted network egress. The agent’s blast radius is bounded by construction.
• One operating model, three deployment topologies. Customer-operated today, BYOC Enterprise next, multi-tenant SaaS later. BYOC is the strongest credential-isolation guarantee: the customer operates the runtime in their own environment, so Aileron never sees credentials. The architecture follows the organization from a single team’s pilot to a company-wide platform.

Thesis

Aileron’s product is the runtime. The runtime is a containerized service customers operate, with a deployment topology that evolves across milestones: v4 customer-operated → v4.x BYOC Enterprise → v5 multi-tenant SaaS.

The agent runs inside a Docker container Aileron composes. Two boundaries make that container safe to give real credentials to. First, the agent reaches Aileron’s actions through aileron-mcp, the in-container MCP server that forwards each tool call to the local daemon where policy and approval are enforced. Second, the container’s HTTPS_PROXY points at Aileron’s credential mediation proxy. Credentialed third-party traffic and the agent’s LLM calls route through Aileron, which identifies the request, evaluates policy, gates approval when required, injects the real credential at the TLS boundary, and forwards upstream. The agent never holds plaintext credentials.

One credential boundary, one action surface, one audit point. Process count scales with throughput, not user count.

Trust zones

Every component falls into one of these zones based on its relationship to plaintext credentials.

Components shipped in v4

The v4 binary set is two cooperating binaries. aileron is the product boundary: the CLI plus the user-scoped local daemon. aileron-mcp is the MCP adapter the agent calls.

aileron (CLI plus local daemon)

One binary, multiple modes:

• aileron launch <agent>: starts a session. Prepares the sandbox, registers the session, wires aileron-mcp into the agent, and runs the agent in the container. The Docker sandbox is the default; --local launches the agent directly on the host instead. Holds the master key briefly during launch, then the daemon owns the session.
• The local daemon (auto-spawned, long-lived): hosts the management plane (sessions, audit, policy, approvals, the connector and action stores) and the data plane (HTTPS proxy plus credential mediation) as logical components. Single-user v4 colocates them all in one process; v4.x and v5 split them.
• aileron status, aileron approval, aileron audit, aileron actions, aileron vault, aileron sessions: user-facing CLI subcommands. Talk to the daemon over HTTPS with the session token.

aileron-mcp (the in-container tool surface)

aileron-mcp is the single canonical way the agent reaches Aileron’s actions, under both host launch and sandbox launch (ADR-0024). It is an MCP server: it advertises each installed action as an MCP tool and forwards a tools/call to the daemon’s /v1/actions/{name}/run. Under sandbox launch it runs as a stdio subprocess of the in-container agent and reaches the daemon over HTTPS. Every MCP-capable agent Aileron launches (Claude, Pi, Goose, OpenCode, Codex) sees the same first-class tool catalog it sees on the host.

The earlier static surface (connector shims on $PATH plus an /etc/aileron/tools.txt manifest) was retired in #959 ↗. MCP is now the only in-container tool surface.

Connector packages (one per integrated system)

Each connector ships a connector spec (ADR-0020). The spec declares the upstream API surface, the curated subset Aileron exposes as actions, and per-operation idempotency, approval, and credential metadata. The daemon loads installed specs to validate connector operations on the HTTPS data plane and to drive request-to-action matching at the proxy. Connectors no longer ship a generated shim binary; the agent reaches every action through aileron-mcp.

Encrypted credential store

Storage layer accessed by the daemon. Vault-centric schema: each vault has its own random vault key; credentials inside are encrypted with that vault key; the vault key is wrapped (encrypted) once per authorized member. Personal vault is the trivial case of a one-member vault. File-backed in v4 (~/.aileron/store/vaults/{vault_id}/...); Postgres plus blob storage in v4.x and v5.

Management plane (logical component inside the daemon)

The control plane. Sessions (start, validate, end). User CLI requests. Policy storage and lookup. Approval orchestration (surface to the user out of band, collect responses). Audit log storage. Multi-user-aware from day one. Never sees plaintext credentials.

Credential mediation: proxy plus credential service (the data plane)

Together they handle all credentialed third-party traffic. Under BYOC both run in the customer’s own infrastructure.

• HTTPS proxy. Accepts HTTPS_PROXY connections from the agent container. Authenticates the session, terminates TLS using a session-local CA installed in the container, and matches each request against the relevant connector spec. When a request uniquely matches a spec operation with an Aileron-managed credential binding, the proxy strips whatever auth the agent attached, injects the real credential, re-establishes TLS upstream, and audits the operation. This is credential-injection (Model A), not an egress allowlist: a request that matches no managed binding is forwarded unmodified. Plaintext credential lives in proxy memory for a single request, zeroed after.
• Credential service. Holds session-keyed material in memory keyed by session ID: master key, unwrapped vault keys cached for the session. Memory footprint per session is small (~KB). Provides decrypt operations to the proxy. Under BYOC it runs in the customer’s own infrastructure.

In v4 these are colocated with the management plane in one daemon process. In v4.x and v5 they split: proxy workers autoscale to traffic, credential service shards by tenant.

Agent container (Docker sandbox)

The composed runtime environment. v4 is Docker-only; Podman is deferred behind a preserved runtime seam, not rejected (#1050 ↗). Contents:

• The agent (Claude Code or other), configured to use HTTPS_PROXY for credentialed outbound HTTPS, with its LLM endpoint pointed at the daemon.
• aileron-mcp, registered with the agent as the Aileron tool surface. The published ghcr.io/alrubinger/aileron-sandbox-base image bakes the binary in for sealed runtimes (#957 ↗); local Tier 0 and devcontainer images take it as a read-only host-mount for version-lockstep with the host CLI.
• bash plus any user-installed tools. v4 does not intercept the shell. Container-only shell-layer mediation was prototyped under #801 ↗ and withdrawn in #952 ↗; container isolation, the credential boundary, and tool-level approval gating cover the named risks (see ADR-0021, Withdrawn).
• The aileron CLI for status queries, audit, approvals, and action browsing.
• The proxy’s CA certificate installed in the system trust store.
• Vault-backed agent credentials materialized at launch from the user’s vault (ADR-0025), with in-container rotations captured back on clean exit.
• Any user-installed third-party tools brought in via devcontainer.json.

Sandbox composition contract

v4 uses .devcontainer/devcontainer.json as the project-local composition substrate (ADR-0017). If the file is absent, Aileron uses ghcr.io/alrubinger/aileron-sandbox-base:<version> directly. If present, Aileron reads standard devcontainer build/image settings and the Aileron-specific customizations.aileron block.

{
  "build": {
    "dockerfile": "Dockerfile"
  },
  "customizations": {
    "aileron": {
      "mediation": "default",
      "approval_surface": "both"
    }
  }
}

customizations.aileron.image selects the BYO-image tier, where Aileron uses the image as supplied and injects the runtime contract at launch: aileron-mcp, session env, manifest mounts, proxy bootstrap, and the session CA. Images that participate in the HTTPS proxy must include the aileron-install-proxy-ca and aileron-run-with-proxy-ca helpers; launch validation checks the contract before the agent starts.

aileron sandbox init scaffolds the starter .devcontainer/devcontainer.json and .devcontainer/Dockerfile. The Dockerfile extends ghcr.io/alrubinger/aileron-sandbox-base:<version>, pre-fills the install recipe for the agent named in --agent (defaults to claude), and ships additional tool snippets commented out for you to enable as needed. Tool installation remains standard container work; Aileron does not maintain an aileron.yaml tool resolver.

Tool discoverability

The agent finds Aileron’s actions the way it finds any MCP server’s tools. aileron-mcp advertises each installed action as a first-class MCP tool (mcp__aileron__<action>) with its description and argument schema, so the LLM can select an action by description rather than by exploring a CLI. This is the same surface MCP-capable agents already use on the host, which is why sandbox launch reaches parity with host launch.

The catalog is curated action.md actions, so it stays small and intentional. A compact dispatcher (list_actions / run_action) for very large catalogs is deferred until catalog cost warrants it. Dynamic refresh, so a newly-installed action surfaces without an MCP restart, is tracked separately in #897 ↗; action install is normally a pre-launch operation, so the restart cost is low today.

The user’s own MCP servers, registered through their devcontainer.json or agent config, coexist independently. Aileron is one MCP server in the agent’s set, not a gateway that aggregates the others.

Network policy

Agents need productive direct egress (read docs, install packages, fetch public data) alongside the mediated credentialed path. v4 ships a tiered model that balances both (ADR-0022).

Vault model: shared by design

A user’s “vault” at runtime is not a single storage unit. It is a view: the union of their personal vault and every shared vault they have been granted access to. v4 ships a vault-centric schema where the personal vault is the trivial case of a one-member shared vault.

Shared vaults are out of scope as a v4 user feature (no team-grant UX, no member-management endpoints). The storage and encryption shape supports them from day one so that v4.x can add the feature without restructuring the data layer.

Encryption model (1Password / Bitwarden pattern)

• Each vault has a randomly-generated vault key.
• All credentials inside the vault are encrypted with that vault key.
• The vault key is wrapped (encrypted) once per authorized member, using each member’s key.
• To decrypt a credential: fetch the member’s wrapping → unwrap with user’s master key → use vault key to decrypt the credential.
• Personal vault is a vault where type=personal and members has exactly one entry.

Storage schema

vaults/
  {vault_id}/
    meta.json
      # name, type (personal|shared), owner, created_at
    members.json
      # member list with roles (owner|contributor|reader)
    key_wrappings/
      {user_id}.wrap
      # vault key wrapped with user's key, one per member
    credentials/
      {credential_id}.enc       # encrypted with vault key
      {credential_id}.meta.json # name, type, action bindings

Grant and revoke (v4.x scope, mechanics established in v4)

• Grant access to a new member. An existing member with the grant role unwraps the vault key with their own key, re-wraps it with the new member’s key, stores {new_user_id}.wrap, updates members.json. No credential ciphertexts are touched.
• Revoke access (rotate). Generate a new vault key. Re-encrypt every credential. Re-wrap for every remaining member. Delete the revoked member’s wrapping. Revocation prevents new decryptions; it does not retroactively invalidate credentials already decrypted in memory.

Agent credentials at launch

Agents that authenticate with their own credential files (Claude’s auth.json, Codex’s auth.json) are seeded from the vault at launch and captured back on clean exit (ADR-0025). The launcher materializes the agent’s declared AuthSpec into the container as env and file bindings, the agent logs in once if the vault is empty, and any in-container rotation is written back to the vault when the session exits cleanly. A SIGINT or SIGTERM salvages the rotation before the container is torn down.

Steady-state architecture

Mid-session on a developer’s laptop in v4. The daemon process hosts the management plane plus the data plane (HTTPS proxy plus credential service) as logical components. The agent reaches Aileron actions through aileron-mcp, and credentialed third-party HTTPS leaves through HTTPS_PROXY.

Aileron actions cross the daemon’s policy and approval boundary through aileron-mcp. Credentialed third-party HTTPS and the agent’s LLM calls cross the data plane. Either way, the plaintext credential is injected outside the container and never enters it.

Startup sequence

What happens between aileron launch claude "..." being typed and the agent beginning work.

Credentialed action flow

Mid-session, the agent invokes an Aileron action through aileron-mcp (e.g., linear.create_issue). The daemon enforces policy and approval, then executes the connector operation through the data plane so the credential is injected outside the container.

The plaintext credential never enters the agent container, never appears in any tool’s memory, never appears in any logged request body the operator sees. The same proxy injection path serves third-party CLIs (such as gh) that respect HTTPS_PROXY. Audit captures the action with attribution to the user.

Deployment topology evolution

Same architecture, three milestones. What changes is where each logical component runs and how it scales. The runtime is Apache-2.0 open core, so customers can operate it themselves at every stage.

v4: Customer-operated (~6 months)

Single developer or team on their own machine. The daemon hosts the management plane and the data plane in one process. Encrypted store is file-backed locally. The agent container’s HTTPS_PROXY points at the local process.

v4.x: BYOC Enterprise (~6 to 12 months)

Customer deploys the runtime backend into their own cloud account. Management plane and data plane split. Proxy workers autoscale to traffic. Credential service shards by team if needed. The runtime stays in the customer’s environment, so Aileron never holds customer credentials.

v5: Multi-tenant SaaS (~12 to 24 months)

Aileron operates the runtime backend. Management plane is multi-tenant. In this topology the HTTPS proxy and the credential service handle credentialed traffic for Aileron-hosted tenants. The strongest credential-isolation guarantee remains BYOC, where the customer operates the runtime in their own environment and Aileron never sees credentials. For the multi-tenant SaaS topology, isolation rests on the operating boundary between tenants rather than on Aileron-as-operator never holding plaintext.

What lives where

Credential isolation under BYOC

BYOC is the strongest credential-isolation guarantee Aileron offers. The customer operates the runtime, the data plane, and the vault in their own infrastructure. Aileron-as-vendor is not in a position to see plaintext credentials at all, because the systems that hold them are operated by the customer rather than by Aileron. This is what makes the isolation property real rather than a policy promise.

Aileron-as-vendor CANNOT see, because the customer operates the runtime:

• Master keys (live only in the customer-operated credential service memory)
• Unwrapped vault keys (live only in the customer-operated credential service memory)
• Decrypted credentials at any moment (decryption happens in the customer’s environment)
• Request bodies after TLS termination at the proxy (the proxy runs in the customer’s environment)
• Upstream HTTPS payloads (mediated in the customer’s environment)
• The plaintext credential injection step (happens in the customer’s environment)

What still applies regardless of topology:

• The encrypted store holds ciphertext only.
• Network traffic between components is TLS-encrypted.
• The audit log records who performed what action and when.
• The customer operates the runtime that writes the audit log, so its integrity rests on infrastructure the customer controls.

Open architectural decisions

Decisions taken in the current design. “(chosen)” means a default position has been taken pending pushback; “(shipped)” means it is implemented in v4.

1. MCP is the canonical in-container tool surface. The agent reaches Aileron actions through aileron-mcp, the same MCP surface used on the host. The earlier shims-on-$PATH plus tools.txt surface is retired. (shipped, #959 ↗)
2. Two cooperating binaries. aileron (CLI plus local daemon, the product boundary) and aileron-mcp (MCP adapter). The daemon is the trust pivot; aileron-mcp is a thin client of its HTTP API. (shipped)
3. One mediation path for credentialed HTTPS. Connector operations, third-party CLIs, and the agent’s LLM calls reach external systems through Aileron, which injects credentials at the TLS boundary. The proxy is cooperative credential-injection (Model A), not an egress allowlist. (chosen / partially shipped)
4. Management plane and data plane colocate in v4, split in v4.x. Interface boundaries are network-call shape from day one so v4.x can deploy them separately without code change. (chosen)
5. Network policy is tiered. Credentialed HTTPS routes through Aileron mediation. Uncredentialed direct egress is forwarded by default for productivity (with audit). Customers can tighten to default-deny plus allowlist for regulated deployments. (chosen)
6. Connector specs are mandatory. Every Aileron connector ships a spec the daemon uses for request-to-action matching and data-plane operation validation. Connectors no longer ship a generated shim. (shipped)
7. Vault-backed agent credentials. Agent auth files are seeded from the vault at launch and rotations are captured back on clean exit. (shipped, ADR-0025)
8. Docker-only, Podman deferred. v4 supports Docker on macOS, Linux, and Windows. The runtime abstraction seam is preserved so Podman can return as a localized change. (shipped, #1050 ↗)
9. Out-of-band approvals. Approval decisions reach the user out of band, never through the agent. v1 ships the CLI-prompt tier; biometric, notification, TUI, and web tiers are Phase 2. (chosen, ADR-0009)
10. Credential service is stateful, narrow. Holds session-scoped material keyed by session ID. Under BYOC it runs in the customer’s own infrastructure. (chosen)
11. Master key delivery. Local secure channel in v4 (chosen). Under BYOC the customer operates the credential service that receives it. Mechanism in v4.x BYOC is still open.

References

The HTTPS forward proxy with credential injection at the TLS boundary is the architecture Infisical published as Agent Vault ↗ (2026-04-22), and the same convergence Anthropic Managed Agents and Browser Use have reached. Aileron incorporates the pattern (not a code dependency in v4) and integrates it with its own policy, audit, vault, and approval systems.

Tracked in GitHub umbrella issue #747 ↗ (Milestone v4). Associated decisions: ADR-0017 (composition), ADR-0019 (data plane), ADR-0022 (network policy), ADR-0024 (MCP parity), and ADR-0025 (vault-backed agent auth).