import MermaidDiagram from '$lib/components/ui/mermaid-diagram.svelte';
import Feature from '$lib/components/ui/feature.svelte';
import * as Alert from '$lib/components/ui/alert/index.js';
import KeyRound from '@lucide/svelte/icons/key-round';
import Database from '@lucide/svelte/icons/database';
import Lock from '@lucide/svelte/icons/lock';
import Bot from '@lucide/svelte/icons/bot';
<div class="not-prose mb-10">
<h2 class="text-4xl font-bold leading-tight tracking-tight text-slate-900 dark:text-slate-50 mb-5">
Aileron is the execution layer for AI-core organizations.
</h2>
<p class="text-xl text-slate-700 dark:text-slate-300 leading-relaxed">
Identity, policy, approvals, audit, and runtime boundaries applied uniformly to every AI agent in the organization.
</p>
</div>
<div class="not-prose my-10 rounded-lg bg-slate-900 p-7 text-slate-100">
<div class="text-xs uppercase tracking-widest text-slate-400 mb-3">The pitch</div>
<p class="text-lg leading-relaxed mb-3">
A decade ago, every company became a software company. That transition required new infrastructure: cloud platforms, deployment pipelines, observability stacks, identity and access management. The companies that built on it rebuilt how they operated. The infrastructure layer captured a generation of value.
</p>
<p class="text-lg leading-relaxed mb-3">
Every company is now becoming an AI company. The work humans did against software is shifting to AI agents doing that work, across every function: engineering, support, sales, operations, research, compliance. That transition needs its own infrastructure layer: identity, policy, approvals, audit, and runtime boundaries that apply uniformly to every agent in the company.
</p>
<p class="text-lg leading-relaxed mb-4">
Aileron is that infrastructure. The execution layer for AI-core organizations.
</p>
<p class="text-xl font-semibold text-white">
Run AI the way you run everything else.
</p>
</div>
## 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.
<div class="not-prose grid gap-4 md:grid-cols-2 my-6">
<Feature icon={KeyRound} title="User-side, key custody">
The user's CLI on their laptop or the user's browser. Holds the master key briefly during launch. Delivers the key to the credential service over a local secure channel. Does not persist the key.
</Feature>
<Feature icon={Database} title="Control plane (never plaintext)">
Sessions, user CLI requests, policy storage, audit storage, approval orchestration, the encrypted credential store. Authenticates users, surfaces approvals, holds encrypted blobs. Cannot decrypt anything.
</Feature>
<Feature icon={Lock} title="Credential mediation (trusted, narrow surface)">
The HTTPS proxy and the credential service. The proxy terminates TLS from container traffic, matches requests against connector specs, evaluates policy, calls the credential service for decryption, injects credentials, re-establishes TLS upstream. The credential service holds session keys in memory. Together they are the data plane. **Under BYOC this credential mediation runs in the customer's own environment, so Aileron-as-operator never reaches plaintext.**
</Feature>
<Feature icon={Bot} title="Agent runtime (untrusted with credentials)">
The agent container. Hosts the agent, bash, the `aileron` CLI, the in-container `aileron-mcp` tool surface, and user-installed tools. `HTTPS_PROXY` set to the credential mediation proxy. The trusted CA cert for the proxy is installed at session start. The agent reaches Aileron actions only through `aileron-mcp`, so every action crosses the daemon's policy and approval boundary.
</Feature>
</div>
## 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](/adr/0024-sandbox-mcp-parity)). 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](https://github.com/ALRubinger/aileron/issues/959). MCP is now the only in-container tool surface.
### Connector packages (one per integrated system)
Each connector ships a **connector spec** ([ADR-0020](/adr/0020-v4-connector-specs-and-shims)). 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](https://github.com/ALRubinger/aileron/issues/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](https://github.com/ALRubinger/aileron/issues/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](https://github.com/ALRubinger/aileron/issues/801) and withdrawn in [#952](https://github.com/ALRubinger/aileron/issues/952); container isolation, the credential boundary, and tool-level approval gating cover the named risks (see [ADR-0021](/adr/0021-v4-shell-layer-mediation), 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](/adr/0025-vault-backed-agent-auth)), 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](/adr/0017-sandbox-composition)). 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.
```json
{
"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](https://github.com/ALRubinger/aileron/issues/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](/adr/0022-v4-tiered-network-policy)).
| Tier | What it covers | How it works |
|---|---|---|
| **Aileron-mediated HTTPS** | Connector operations Aileron credentials, the agent's LLM calls, third-party CLI calls to known-credentialed destinations | Connector operations resolve through the daemon; credentialed third-party HTTPS flows through `HTTPS_PROXY`. The proxy matches a request to a spec operation, injects the managed credential, and audits. |
| **Direct uncredentialed egress** | Public documentation, package registries (npm, pypi, brew, apt), public APIs, uncredentialed search | Forwarded by the proxy unmodified (audited, no credential injected). Customers can configure default-deny plus allowlist for a stricter posture. |
| **Private network ranges** | `127.0.0.0/8`, `192.168.0.0/16`, link-local, ULA, CGNAT | Denied by default, with an explicit bypass only for the loopback path to the Aileron proxy. |
| **Non-HTTPS egress** | SSH, database connections, custom protocols | Outside the proxy's scope. The Docker sandbox network policy handles allow/deny. v4 does not credential-mediate non-HTTPS. |
<Alert.Root class="my-6">
<Alert.Title>Residual exfil risk</Alert.Title>
<Alert.Description>
With permissive uncredentialed egress, a compromised agent could send context data (user prompts, tool results, files it has read) to attacker-controlled endpoints. Mitigated by audit, approval gating on the actions that introduce sensitive data, and network-layer destination categorization. Credentials cannot be exfiltrated regardless because they never enter the container; only context-data exfil is residual, and that is fundamentally an agent-policy concern, not a network-policy one.
</Alert.Description>
</Alert.Root>
## 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](/adr/0025-vault-backed-agent-auth)). 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`.
<MermaidDiagram client:load graph={`graph TB
subgraph laptop["💻 User's Laptop"]
direction TB
subgraph user_side["User-side"]
CLI["aileron launch (transient at start)"]
end
subgraph runtime_backend["aileron daemon (long-lived process)"]
direction TB
subgraph mgmt["Management plane"]
Mgmt["Sessions, policy, approvals, audit, actions"]
Store[("Encrypted Store")]
Mgmt --> Store
end
subgraph data_plane["Data plane (credential mediation)"]
Proxy["HTTPS proxy"]
CredSvc["Credential service (session keys)"]
Proxy <-->|"decrypt"| CredSvc
end
Mgmt <-->|"policy, approvals"| Proxy
CredSvc -->|"fetch blobs"| Store
end
subgraph agent_zone["Agent runtime"]
AgentContainer["Agent container (Docker sandbox)"]
Agent["Agent: Claude Code"]
Bash["bash + user tools"]
AileronCli["aileron CLI"]
MCP["aileron-mcp (MCP server)"]
AgentContainer --- Agent
AgentContainer --- Bash
AgentContainer --- AileronCli
AgentContainer --- MCP
end
end
External["External APIs"]
CLI -.->|"key"| CredSvc
CLI -->|"session bootstrap"| Mgmt
Agent -->|"tools/call"| MCP
MCP -->|"actions, policy, approval"| Mgmt
Bash -->|"credentialed HTTPS via HTTPS_PROXY"| Proxy
AileronCli -->|"queries"| Mgmt
Proxy -->|"injects, TLS upstream"| External
classDef purple fill:#f3e8ff,stroke:#9333ea,color:#581c87
classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef green fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef amber fill:#fef3c7,stroke:#d97706,color:#78350f
classDef red fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class CLI purple
class Mgmt,Store blue
class Proxy,CredSvc green
class AgentContainer,Agent,Bash,AileronCli,MCP amber
class External red
`} />
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.
<MermaidDiagram client:load graph={`sequenceDiagram
autonumber
actor User
participant CLI as aileron launch
participant Mgmt as Management plane
participant CredSvc as Credential service
participant Container as Agent container
User->>CLI: aileron launch claude "..."
CLI->>CLI: Resolve daemon (auto-spawn if needed)
CLI->>User: Prompt for master key (if vault locked)
User->>CLI: Master key
CLI->>Mgmt: Start session for user X
Mgmt->>CLI: session_id, session bearer, HTTPS_PROXY URL, CA cert
CLI->>CredSvc: Deliver master key (local secure channel)
CredSvc->>CredSvc: Store session entry: session_id → master_key
CLI->>Container: docker run sandbox<br/>(HTTPS_PROXY, session token,<br/>CA cert installed,<br/>aileron-mcp registered,<br/>vault-backed agent auth)
Container->>Container: Agent starts (no master key, no plaintext)
CLI->>CLI: Hand off to the daemon-owned session
Container->>User: Agent begins 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.
<MermaidDiagram client:load graph={`sequenceDiagram
autonumber
participant Agent
participant MCP as aileron-mcp
participant Mgmt as Management plane
participant Proxy as HTTPS proxy
participant CredSvc as Credential service
participant Store as Encrypted Store
participant Linear as api.linear.app
Agent->>MCP: tools/call linear.create_issue
MCP->>Mgmt: POST /v1/actions/linear.create_issue/run
Mgmt->>Mgmt: Resolve action, evaluate policy
Mgmt-->>Agent: 202 Accepted + review_url (approval required)
Mgmt->>User: Render approval out of band (CLI / notification / web)
User-->>Mgmt: Approve
Mgmt->>Proxy: Execute connector operation
Proxy->>CredSvc: Decrypt Linear credential for session
CredSvc->>Store: Fetch wrapped vault key (if not cached)
Store-->>CredSvc: Wrapped vault key
CredSvc->>CredSvc: Unwrap with master key (cache for session)
CredSvc->>Store: Fetch encrypted Linear credential
Store-->>CredSvc: Ciphertext
CredSvc-->>Proxy: Plaintext credential
Proxy->>Proxy: Inject real bearer at the TLS boundary
Proxy->>Linear: POST /issues (TLS upstream)
Linear-->>Proxy: 201 Created
Proxy->>Proxy: Zero plaintext credential
Proxy->>Mgmt: Audit: action completed
Mgmt-->>MCP: result (agent polls via check_action_status)
MCP-->>Agent: created issue #123
`} />
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.
<MermaidDiagram client:load graph={`graph LR
subgraph laptop["💻 Developer's laptop"]
CLI["aileron CLI"]
subgraph backend["aileron daemon (one process)"]
Mgmt["Mgmt plane"]
Proxy["HTTPS proxy"]
CredSvc["Cred svc"]
end
Store[("~/.aileron/store")]
Container["Agent container"]
Mgmt --> Store
CredSvc --> Store
Proxy <--> CredSvc
Proxy <--> Mgmt
CLI -.->|"key"| CredSvc
Container -->|"HTTPS_PROXY"| Proxy
end
External["External APIs"]
Proxy --> External
classDef purple fill:#f3e8ff,stroke:#9333ea,color:#581c87
classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef green fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef amber fill:#fef3c7,stroke:#d97706,color:#78350f
classDef red fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class CLI purple
class Mgmt,Store blue
class Proxy,CredSvc green
class Container amber
class External red
`} />
### 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.
<MermaidDiagram client:load graph={`graph LR
subgraph cloud["☁️ Customer's cloud account"]
Mgmt["Management plane (multi-user)"]
Proxy["HTTPS proxy (autoscaled)"]
CredSvc["Credential service (session keys)"]
Store[("Postgres + S3")]
Mgmt --> Store
CredSvc --> Store
Proxy <--> CredSvc
Proxy <--> Mgmt
end
subgraph laptop_a["💻 User A"]
CLI_A["aileron CLI"]
Container_A["Agent container"]
end
subgraph laptop_b["💻 User B"]
CLI_B["aileron CLI"]
Container_B["Agent container"]
end
External["External APIs"]
CLI_A -.->|"key"| CredSvc
CLI_B -.->|"key"| CredSvc
Container_A -->|"HTTPS_PROXY"| Proxy
Container_B -->|"HTTPS_PROXY"| Proxy
Proxy --> External
classDef purple fill:#f3e8ff,stroke:#9333ea,color:#581c87
classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef green fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef amber fill:#fef3c7,stroke:#d97706,color:#78350f
classDef red fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class CLI_A,CLI_B purple
class Mgmt,Store blue
class Proxy,CredSvc green
class Container_A,Container_B amber
class External red
`} />
### 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.
<MermaidDiagram client:load graph={`graph LR
subgraph aileron_cloud["☁️ Aileron multi-tenant cloud"]
Mgmt["Management plane (tenant-aware)"]
Store[("Postgres + blob (per-tenant)")]
Mgmt --> Store
Proxy["HTTPS proxy (autoscaled)"]
CredSvc["Credential service (sharded by tenant)"]
Proxy <--> CredSvc
CredSvc --> Store
Mgmt <--> Proxy
Container["Agent container"]
end
User["💻 User's browser / laptop"]
External["External APIs"]
User -.->|"master key"| CredSvc
User --> Mgmt
Container -->|"HTTPS_PROXY"| Proxy
Proxy --> External
classDef purple fill:#f3e8ff,stroke:#9333ea,color:#581c87
classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef green fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef amber fill:#fef3c7,stroke:#d97706,color:#78350f
classDef red fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
class User purple
class Mgmt,Store blue
class Proxy,CredSvc green
class Container amber
class External red
`} />
### What lives where
| Component | v4 | v4.x | v5 |
|---|---|---|---|
| Management plane | Colocated in the daemon on user's laptop | Separate service in customer cloud | Aileron's cloud, multi-tenant |
| HTTPS proxy | Colocated in the daemon | Autoscaled worker pool in customer cloud | Autoscaled worker pool in Aileron's cloud |
| Credential service | Colocated in the daemon | Separate service in customer cloud | Sharded by tenant in Aileron's cloud |
| Encrypted store | Local files in `~/.aileron/store/vaults/` | Customer's Postgres + blob storage | Aileron's Postgres + object storage, per-tenant prefixed |
| Master key custody | User's laptop (briefly) → credential service | User's device → credential service in customer cloud | User's device → credential service in Aileron's cloud |
| Agent container | User's laptop (Docker sandbox) | User's laptop or customer cloud workspace | User's laptop or Aileron cloud |
| Audit destination | Local audit log | Customer-configured SIEM | Customer-configured SIEM (export from Aileron) |
## 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.
<Alert.Root class="my-6">
<Alert.Title>Threat model boundaries</Alert.Title>
<Alert.Description>
Under BYOC the credential boundary protects against Aileron-as-vendor seeing plaintext, because the customer operates the runtime end to end. It does not protect against compromise of the customer's own infrastructure, nor against the LLM provider seeing prompts and tool results.
</Alert.Description>
</Alert.Root>
## 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](https://github.com/ALRubinger/aileron/issues/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](/adr/0025-vault-backed-agent-auth))
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](https://github.com/ALRubinger/aileron/issues/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](/adr/0009-user-channel))
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](https://infisical.com/blog/agent-vault-the-open-source-credential-proxy-and-vault-for-agents) (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](https://github.com/ALRubinger/aileron/issues/747) (Milestone v4). Associated decisions: [ADR-0017](/adr/0017-sandbox-composition) (composition), [ADR-0019](/adr/0019-v4-https-data-plane) (data plane), [ADR-0022](/adr/0022-v4-tiered-network-policy) (network policy), [ADR-0024](/adr/0024-sandbox-mcp-parity) (MCP parity), and [ADR-0025](/adr/0025-vault-backed-agent-auth) (vault-backed agent auth).