AileronControlPlane

Prepare for Liftoff

We’re about to take your first flight with Aileron. In under 5 minutes, you’ll be securely equipping Claude Code to use your real Gmail and Google Calendar account. Along the way we’ll introduce Connectors and Actions, a joyful way to add powerful features to your agent. Your agent never sees the keys to your private services, and you always retain approval before taking an irreversible action like sending an email. Let’s take off.

Estimated time: 5 minutes.

What happens:

  • Summarize your recent emails
  • See how much time you’re planning to spend in meetings next week
  • Draft an email
  • Approve an irreversible action before it lands
  • Review the audit trail of what was done

…all executed in a sandboxed environment without giving your agent or LLM direct access to your Google Account.

Preflight Checklist

aileron launch runs the agent inside the container, so you do not install the agent CLI on your host. You only need a credential the launcher can seed into the sandbox. Two agents are supported.

Claude needs either a Claude Pro/Max subscription or an Anthropic API key. Subscription mode signs in with a Claude account via OAuth login and is the default. API-key mode reads an Anthropic API key from ANTHROPIC_API_KEY. Pick the mode at launch with --claude-auth=subscription|api-key, or answer the first-run prompt where Enter selects subscription.

Codex needs either a Codex/OpenAI subscription or an OpenAI API key. Both agents seed the credential the same way. First launch runs an in-container login, or a host-side acquirer stores the credential in the vault before the container starts. The vault then renders it into every later launch silently. See Sandbox Agent Auth for the full mode-selection and seeding detail.

Docker installed and the daemon running. Docker Desktop is the easy path on macOS and Windows. aileron launch runs the agent inside a container by default, so the daemon must be reachable before you launch.

Gmail and Calendar must be enabled. The OAuth dance opens in your default browser.

1. Install Aileron

Requires Homebrew.

brew install --cask ALRubinger/aileron/aileron

Prefer to compile it yourself? See Building from Source.

Verify:

aileron version

You should see the installed version:

aileron 0.0.17

2. Install Actions for Gmail and Calendar

The aileron-connector-google connector publishes a curated suite of Gmail and Calendar actions. Install them all in one command:

aileron action add-suite github://ALRubinger/aileron-connector-google/suite.toml@latest

@latest resolves to the connector’s most recent release. Pin to a specific version with @v0.0.6, or to a git commit with @<sha>.

This is the first command that touches your local secret store, so Aileron walks you through creating one before recording trust. You’ll see this prompt now:

  Creating a new Aileron vault.

  The passphrase you choose protects all secrets in this vault.
  It is never stored, transmitted, or recoverable. No one can
  read it, tell you what it is, or help you retrieve it.

  If you lose this passphrase, you must delete the vault file
  (~/.aileron/secrets.json) and re-add all secrets.

  Store this passphrase securely. Do not share it.

Vault passphrase: ********
Confirm passphrase: ********

Pick a passphrase and confirm it. The vault is encrypted at rest with Argon2id ↗. You unlock it once per session and every later command reuses that unlocked state. See The Vault for what it protects you from.

After the vault is up, the CLI prompts to trust the publisher. The key is fetched from keys/publisher.pub on the repo’s default branch:

Publisher github://ALRubinger/aileron-connector-google is not yet trusted.
  Aileron will fetch keys/publisher.pub on the publisher's default branch
  and use that key to verify signed installs from this publisher.
Trust publisher github://ALRubinger/aileron-connector-google? [y/N]: y
✓ Trusted publisher github://ALRubinger/aileron-connector-google
  Fingerprint: sha256:...
  Keyring: /Users/you/.aileron/keyring.json

The trust prompt fires once for the publisher and applies to every action in the suite. Aileron then walks each action through preview and install in declaration order. The connector tarball is fetched once and reused. Google’s OAuth consent screen pops up on the first action, and the bound credential is reused for the rest. The CLI prints a per-action summary at the end.

The connector’s publisher already shipped a Desktop OAuth client_id and client_secret bound at release time, so there’s no Google Cloud Console setup on your end. The token bytes are encrypted at rest; Aileron refreshes them transparently when they near expiry, and the connector never sees the credential.

If you’d rather drive each step yourself, the single-action form aileron action add <action-FQN> still works, and aileron keyring trust <authority> runs the trust step on its own. If you maintain a connector and want to publish your own suite, see Authoring an Action Suite.

3. Launch Claude Code through Aileron

aileron launch claude

aileron launch runs the agent inside a Docker container by default. The container is the sandbox: Claude Code runs in an isolated environment, never on your host. Because that isolation is the trust boundary, the sandboxed launch starts Claude Code with --dangerously-skip-permissions, so the agent works without stopping for per-command confirmation. The sandbox is what makes that safe. The agent can move fast inside a box it cannot escape.

To launch the agent directly on the host instead, add --local:

aileron launch --local claude

The host launch keeps a narrower posture. It pre-approves only the agent’s shell commands and Aileron’s own tools, not blanket skip-permissions.

The first launch resolves how Claude authenticates. Subscription mode signs in with a Claude Pro/Max account via OAuth login and is the default. API-key mode uses an Anthropic API key from ANTHROPIC_API_KEY. Pass --claude-auth=subscription or --claude-auth=api-key to pre-select the mode, or answer the first-run prompt where Enter selects subscription. The launcher prints the active mode as Claude auth mode: subscription (Pro/Max) or Claude auth mode: API key. See Sandbox Agent Auth for the full mode-selection and seeding detail.

In subscription mode, the first launch walks you through the cloud login right here. Aileron prints the authorize URL and opens it in your browser:

To authorize Claude, open https://claude.ai/oauth/authorize?... in your browser and paste back the code shown.

Sign in with your Claude Pro/Max account in the browser, copy the code the page shows, and paste it back at the prompt:

Paste the code from your browser and press Enter:

The paste stays on your host terminal, never inside the container. Aileron exchanges the code, seeds the credential into your vault, and the credential is reused on later launches. This first-run flow happens once.

You’ll see a banner like:

✈️  Aileron — webapp http://127.0.0.1:54321 — session 01HK6...

Claude Code is now a normal Claude Code session, with a tool catalog that includes the actions you just installed.

4. Drive the actions from the agent

In the Claude Code prompt, try:

Summarize my five most recent emails.

Claude picks list_recent_emails, Aileron executes it inside the WASM sandbox against gmail.googleapis.com, returns {id, threadId} pairs, Claude fans out parallel get_email calls for the metadata, and you get a summary.

A few more prompts to exercise the rest of the surface:

What’s on my calendar this week?

Routes to list_upcoming_events.

Draft a reply to the last email from Andrew thanking him and confirming Tuesday.

Routes to get_email (to read context) then draft_email, which lands a draft in your Gmail Drafts folder. Drafts are reversible, so this action is not gated; the existing manual “click Send in Gmail” step is the human review.

5. Approve an irreversible action

So far every call has been a read or a reversible write. Now do something the agent cannot take back on its own. In Claude Code:

Add a 30-minute “Aileron test event” to my calendar tomorrow at 10am.

Claude picks create_calendar_event. This one is different. create_calendar_event and send_email are gated for per-call approval because their effects are not reversible (see the connector’s README ↗ for why). Instead of executing immediately, the daemon parks the call, records an approval.requested event in the audit log, and Claude’s tool call blocks.

Open the webapp URL printed in the launch banner from Section 3 and visit /approvals. You’ll see a card for the pending call showing:

  • The action name and connector
  • A kind badge (here, a generic “ACTION”; for send_email it reads “COMMS SEND”)
  • The rendered preview from the connector’s [approval.preview] directive: for the calendar event, the title, start time, duration, and target calendar
  • The raw arguments as JSON, in case the rendered preview hides something you want to verify
  • Two buttons, Approve and Deny, with an optional reason field for denials

Click Approve. The blocked tool call unblocks, the daemon records approval.approved and execution.succeeded, and the event appears in your Calendar. If you click Deny instead, the tool call returns a denial and Claude responds with the failure. Nothing is written.

If you’d rather jump to a specific pending approval from the shell, aileron open approval <approval-id> opens the webapp focused on that card. The launch-banner URL is the primary path; this is the shortcut for scripts and for when the banner has scrolled off.

The approval surface is the seam where the agent stops and you start. See Proof of Control for why every approval, including the time-to-decision and outcome, is recorded alongside the execution.

6. Inspect what happened

In a separate terminal, ask the runtime for the receipt:

aileron audit list                 # every event: installs, executions, approvals
aileron audit show <audit-id>      # full record for one event

audit list walks the events from this Getting Started: the action.installed, connector.installed, and binding.created entries from Section 2; the execution.started / execution.succeeded pairs for the read calls in Section 4; and the approval.requested → approval.approved → execution.succeeded triple for the calendar event you just approved. Pick the audit-id of that last execution.succeeded and pass it to audit show to see the full record: action, connector version, binding identity, duration, disposition, payload.

The audit log is the receipt for everything the agent did on your behalf, recorded under ~/.aileron/audit/audit-YYYY-MM-DD.jsonl (daily-rotated, user-scope). Paired with the install consent and keyring trust records from Section 2, you can answer two questions for any action: “did I authorize this capability?” and “what did the agent actually do with it?”

For end-to-end timing or correlation with the rest of your agent stack, Aileron also emits OpenTelemetry traces. See Observability for what gets emitted, the span attribute schema, and how to wire it up.

What you’ve built

You ran a real agent against a real LLM. Your installed actions reached the agent through Aileron’s MCP server (one tool per action, description drawn from the action’s Markdown body). When the LLM picked one, the agent host dispatched the call back through MCP to the daemon, which executed the action inside a WASM sandbox, mediated OAuth tokens at the network boundary so the LLM never held a credential, and recorded every decision and execution in an audit log.

This is the loop the rest of the docs builds on. From here: