Aileron Docs

Getting Started

This guide walks the full end-to-end flow on a fresh machine: build the binaries, trust a publisher, install the aileron-connector-google reference connector, bind a real Google account, and run Claude Code with Gmail and Calendar actions exposed via Aileron’s MCP server.

By the end you will have asked Claude Code “summarize my five most recent emails”, watched it pick a Gmail tool Aileron published, and seen Aileron execute it inside the WASM sandbox against the real Google API — all without Claude ever holding your OAuth token.

Prerequisites

  • Go 1.25 or newer. Aileron’s modules require it. go version should report at least go1.25.0.
  • Task. All build commands go through task. brew install go-task on macOS.
  • Claude Code installed and configured with an Anthropic API key in ANTHROPIC_API_KEY. Aileron’s launcher routes Claude Code’s LLM calls through an embedded gateway, but it does not supply or replace your API key.
  • A Google account. Gmail and Calendar must be enabled. The OAuth dance opens in your default browser.
  • jq and openssl for the one-liner that trusts the connector’s signing key.

There is no brew install aileron yet — for now you build from source. That is the path this guide follows.

1. Build the binaries

git clone https://github.com/ALRubinger/aileron.git
cd aileron
task build:cli build:server build:mcp build:sh

This produces four binaries in build/:

BinaryPurpose
aileronThe CLI you use for install, binding, status, audit, and launch.
serverThe standalone Aileron HTTP server. The CLI talks to it.
aileron-mcpThe MCP server that exposes installed actions to the agent. aileron launch resolves it as a sibling of the aileron binary.
aileron-shThe policy-enforced shell shim used by aileron launch.

Put the build directory on your PATH so the launcher can find aileron-mcp next to aileron:

export PATH="$PWD/build:$PATH"

Verify:

aileron version

2. Start the standalone server

The CLI is a thin HTTP client over the OpenAPI-spec’d server. Install, binding, status, and audit commands all go to http://localhost:8721/v1. Start the server on that port and leave it running in its own terminal:

AILERON_ADDR=:8721 ./build/server

On first launch you will be prompted to create a vault and choose a passphrase. The vault is encrypted at rest with Argon2id; see The Vault for what it protects you from. The vault file lives at ~/.aileron/secrets.json and is shared by the standalone server and aileron launch — bind a credential here once and the launched agent picks it up automatically.

3. Trust the connector’s publisher key

Every connector install verifies an ed25519 signature against keys you have explicitly trusted (per ADR-0002). Without a trusted key for the publisher’s authority, install fails closed before fetching anything.

Download the aileron-connector-google publisher key and trust it:

curl -fsSLO https://raw.githubusercontent.com/ALRubinger/aileron-connector-google/main/keys/publisher.pub
aileron keyring trust github://ALRubinger/aileron-connector-google publisher.pub

You should see:

✓ Trusted publisher github://ALRubinger/aileron-connector-google
  Fingerprint: sha256:...
  Keyring: /Users/you/.aileron/keyring.json

Confirm it landed:

aileron keyring list

4. Install an action

Pick the latest release tag from the connector’s releases page and install one of its action templates. Versions in this guide use 0.0.6 — substitute the current tag.

aileron action add github://ALRubinger/aileron-connector-google/actions/[email protected]

Aileron resolves the action’s connector dependency, fetches the connector tarball from the GitHub release, verifies the signature against your trusted key, computes the content hash, and walks you through a consent prompt for each new connector and the action itself. Confirm each step.

When the install completes, the action file is at ~/.aileron/actions/list-recent-emails.md (you own it — edit it freely) and the connector is in the content-addressed store at ~/.aileron/store/.

Add a couple more so the agent has room to compose:

aileron action add github://ALRubinger/aileron-connector-google/actions/[email protected]
aileron action add github://ALRubinger/aileron-connector-google/actions/[email protected]
aileron action add github://ALRubinger/aileron-connector-google/actions/[email protected]

The connector is fetched once; subsequent action installs reuse it.

5. Bind your Google account

Action templates declare what credential they need; binding is how you tell Aileron which one of your accounts to use. The Google connector declares an OAuth2 capability with read+compose scopes for Gmail and read+events scopes for Calendar.

If aileron action add already prompted you to bind during install, skip ahead. Otherwise:

aileron binding setup github://ALRubinger/aileron-connector-google

You’ll be asked for an identity (e.g. personal, work) — this is just a label that disambiguates multiple accounts you might bind under the same connector. Aileron then opens your browser to Google’s OAuth consent screen. Approve, and Google redirects to a loopback URL Aileron is listening on. The CLI captures the code, exchanges it for a refresh token server-side, and stores the result in your vault.

The connector’s publisher already shipped a Desktop OAuth client_id and client_secret bound at release time, so there is no Google Cloud Console setup on your end.

Confirm the binding landed:

aileron binding list

You should see something like:

oauth2/aileron-connector-google/personal  oauth2  google  ...

The token bytes are encrypted at rest. Aileron refreshes them transparently when they near expiry; the connector never sees the credential. See The Vault for how the credential travels at execution time.

6. Launch Claude Code through Aileron

aileron launch claude

You’ll see a banner like:

✈️  Aileron — webapp http://127.0.0.1:54321 — session 01J... — log ~/.aileron/logs/...

What happened under the hood:

  • Aileron started a per-session embedded gateway on an ephemeral localhost port.
  • It set ANTHROPIC_BASE_URL to that gateway URL for the Claude Code child process, so Claude’s LLM calls now flow through Aileron.
  • It registered aileron-mcp as an MCP server for the session. On startup, aileron-mcp queries /v1/actions and generates one MCP tool per installed action — list_recent_emails, get_email, list_upcoming_events, draft_email.
  • The vault is shared with the standalone server’s persistent vault at ~/.aileron/secrets.json, so the binding you set up in step 5 is in scope.

Claude Code is now a normal Claude Code session, with a tool catalog that includes the actions Aileron published.

7. Drive the actions from the agent

In the Claude Code prompt, try:

Summarize my five most recent emails.

Claude picks list_recent_emails (it sees one tool per installed action thanks to MCP discovery), 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.

send-email and create-calendar-event are gated for per-call approval because their effects are not reversible (see the connector’s README for why). When Claude proposes one of those, the approval prompt fires through the launch comms channel and Claude’s tool call blocks until you decide.

8. Inspect what happened

In a separate terminal (with the standalone server still running), see what the runtime knows:

aileron status               # version, listen addr, action/connector/binding counts, vault state
aileron action audit         # every installed action and the capabilities it can exercise
aileron binding list         # bound credentials with their last-used timestamp
aileron audit list           # action-execution audit log: every call, with inputs and outcome

The audit log is the receipt for everything the agent did on your behalf. Each entry names the action, the connector version, the binding identity, the duration, and the disposition. Combined with the install consent log, you can answer two questions for any action: “did I authorize this capability?” and “what did the agent actually do with it?”

What you’ve built

You ran a real LLM through a local proxy that augmented its tool catalog with installed actions, executed those actions 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: