import HighlightCard from '$lib/components/ui/highlight-card.svelte';
import LiftoffPreflight from '$lib/components/ui/liftoff-preflight.svelte';
import OsInstallTabs from '$lib/components/ui/tabs/os-install-tabs.svelte';
import { latestRelease } from '$lib/data/release';
<HighlightCard>
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](/concepts/connectors/) and [Actions](/concepts/connectors/), 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.
</HighlightCard>
<HighlightCard variant="muted">
**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.
</HighlightCard>
## Preflight Checklist
<LiftoffPreflight client:load />
## 1. Install Aileron
<OsInstallTabs platforms={[
{
value: "macos",
label: "macOS",
lang: "sh",
note: 'Requires <a href="https://brew.sh">Homebrew</a>.',
code: "brew install --cask ALRubinger/aileron/aileron",
},
{
value: "linux",
label: "Linux",
variants: [
{
value: "deb",
label: "Debian / Ubuntu (.deb)",
lang: "sh",
code: `curl -LO https://github.com/ALRubinger/aileron/releases/latest/download/aileron_${latestRelease.version}_linux_amd64.deb\nsudo dpkg -i aileron_${latestRelease.version}_linux_amd64.deb`,
},
{
value: "rpm",
label: "RHEL / Fedora (.rpm)",
lang: "sh",
code: `curl -LO https://github.com/ALRubinger/aileron/releases/latest/download/aileron_${latestRelease.version}_linux_amd64.rpm\nsudo rpm -i aileron_${latestRelease.version}_linux_amd64.rpm`,
},
{
value: "apk",
label: "Alpine (.apk)",
lang: "sh",
code: `curl -LO https://github.com/ALRubinger/aileron/releases/latest/download/aileron_${latestRelease.version}_linux_amd64.apk\nsudo apk add --allow-untrusted aileron_${latestRelease.version}_linux_amd64.apk`,
},
],
},
{
value: "windows",
label: "Windows",
note: "Windows support is still being verified on real hardware. Please file an issue if anything does not work.",
variants: [
{
value: "scoop",
label: "Scoop",
lang: "powershell",
code: `scoop bucket add aileron https://github.com/ALRubinger/scoop-aileron\nscoop install aileron`,
},
{
value: "zip",
label: "Manual (.zip)",
lang: "powershell",
note: "Extract the zip and add the directory to PATH.",
code: `Invoke-WebRequest -Uri https://github.com/ALRubinger/aileron/releases/latest/download/aileron_${latestRelease.version}_windows_amd64.zip -OutFile aileron.zip\nExpand-Archive aileron.zip -DestinationPath $env:USERPROFILE\\aileron`,
},
],
},
]} client:load />
Prefer to compile it yourself? See [Building from Source](/development/building-from-source/).
Verify:
```sh
aileron version
```
You should see the installed version:
<pre><code>{`aileron ${latestRelease.version}`}</code></pre>
## 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:
```sh
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](https://datatracker.ietf.org/doc/html/rfc9106). You unlock it once per session and every later command reuses that unlocked state. See [The Vault](/concepts/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](/guides/authoring-an-action-suite/).
## 3. Launch Claude Code through Aileron
```sh
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`:
```sh
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](/development/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](https://github.com/ALRubinger/aileron-connector-google#what-it-ships) 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](/concepts/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:
```sh
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](/guides/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:
- [Concepts → Deterministic Agentic Execution](/concepts/deterministic-agentic-execution/) — why this is the architecturally load-bearing seam.
- [Concepts → Actions](/concepts/actions/) and [Connectors](/concepts/connectors/) — the model behind what you just installed.
- [Guides → Authoring an Action](/guides/authoring-an-action/) — write your own action template against an existing connector.
- [Guides → Authoring a Connector](/guides/authoring-a-connector/) — ship a connector for a service Aileron does not yet have.
- [CLI Reference](/cli/) — every command grouped by concern.