{"slug":"cli-launcher-reference","title":"CLI launcher reference","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# CLI launcher reference\r\n\r\nLast validated: Apr 9, 2026\r\n\r\nAperture by Tailscaleis currently [in alpha](https://tailscale.com/docs/reference/tailscale-release-stages#alpha).\r\n\r\nThe Aperture launcher (`aperture-cli`) is a command-line interface (CLI) that configures and runs coding agents pre-connected to your [Aperture](https://tailscale.com/docs/aperture) proxy. It handles environment variables, configuration files, and provider type selection automatically, so you can start a coding session without editing configuration by hand.\r\n\r\nThis page is part of the [Aperture reference](https://tailscale.com/docs/aperture/reference) documentation.\r\n\r\n## [Prerequisites](https://tailscale.com/docs/aperture/cli-launcher\\#prerequisites)\r\n\r\nBefore you use the launcher, confirm you have the following:\r\n\r\n- A running Aperture proxy with at least one [configured provider](https://tailscale.com/docs/aperture/configuration).\r\n- Network access to the Aperture host URL (default: `http://ai`).\r\n- At least one [supported coding agent](https://tailscale.com/docs/aperture/cli-launcher#supported-agents) installed on your device. If you don't have one, the launcher provides install commands for each agent.\r\n- Go 1.26 or later installed on the device you plan to install the `aperture-cli` on.\r\n\r\n## [Install the launcher](https://tailscale.com/docs/aperture/cli-launcher\\#install-the-launcher)\r\n\r\nYou can install the Aperture launcher using `go install` or by building the launcher from the [Aperture repository on GitHub](https://github.com/tailscale/aperture-cli). These instructions cover using `go install`.\r\n\r\n1. Install the aperture-cli using `go install`:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ngo install github.com/tailscale/aperture-cli/cmd/aperture@latest\r\n```\r\n\r\n2. Start the `aperture-cli` launcher:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\naperture\r\n```\r\n\r\n\r\n## [Connect to Aperture](https://tailscale.com/docs/aperture/cli-launcher\\#connect-to-aperture)\r\n\r\nThe launcher connects to your Aperture proxy on startup and verifies your provider configuration.\r\n\r\n1. Run the launcher:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\naperture\r\n```\r\n\r\n\r\n\r\nBy default, the launcher connects to `http://ai`. To use a different host, open the settings menu and add or select an endpoint under **Aperture Endpoints**. The launcher persists your endpoint selection in `settings.json`.\r\n\r\n2. Wait for the preflight check to complete.\r\n\r\nThe launcher queries the Aperture proxy for its list of configured providers and their API compatibility. If the host is unreachable, the launcher prompts you to enter a different URL.\r\n\r\n3. After a successful connection, the launcher displays the main menu with your available coding agents.\r\n\r\nThe launcher saves the connected host to your settings and uses it automatically on the next launch.\r\n\r\n\r\n### [Manage multiple endpoints](https://tailscale.com/docs/aperture/cli-launcher\\#manage-multiple-endpoints)\r\n\r\nYou can configure multiple Aperture proxy URLs and switch between them.\r\n\r\n1. From the main menu, press `s` to open settings.\r\n\r\n2. Select **Aperture Endpoints**.\r\n\r\n3. Add or remove endpoints. Select an endpoint to make it the active host. The launcher uses the active endpoint on startup.\r\n\r\n\r\nTo delete an endpoint, highlight it and press `d`.\r\n\r\n## [Launch a coding agent](https://tailscale.com/docs/aperture/cli-launcher\\#launch-a-coding-agent)\r\n\r\nAfter the launcher connects to Aperture, select a coding agent and provider type to start a coding session.\r\n\r\n### [Select an agent](https://tailscale.com/docs/aperture/cli-launcher\\#select-an-agent)\r\n\r\nThe main menu lists all coding agents that the launcher detected on your device. Agents without an installed binary do not appear.\r\n\r\n```markup\r\nConnected to http://ai (3 providers)\r\n\r\nWhich editor do you want to use?\r\n\r\n [0] Last Used: Claude Code - Google Vertex\r\n [1] Claude Code\r\n [2] Gemini CLI\r\n [3] OpenCode\r\n\r\n [i] Install agents\r\n [s] Settings\r\n [q] Quit\r\n\r\nSelection (default: 0):\r\n```\r\n\r\nThe `[0] Last Used` shortcut launches the same agent and provider type combination from your previous session. Press `0` or `Enter` to relaunch it.\r\n\r\nIf an agent you expect is missing from the list, the launcher couldn't find its binary. Refer to the [troubleshooting section](https://tailscale.com/docs/aperture/cli-launcher#agent-binary-not-found) for resolution steps.\r\n\r\n### [Select a provider type](https://tailscale.com/docs/aperture/cli-launcher\\#select-a-provider-type)\r\n\r\nAfter selecting an agent, choose a provider type. The launcher displays only provider types that are compatible with your configured Aperture providers.\r\n\r\nFor example, if no provider in your Aperture configuration supports the Amazon Web Services (AWS) Bedrock API, the launcher hides the Bedrock option from the Claude Code provider type list.\r\n\r\n### [Automatic selection](https://tailscale.com/docs/aperture/cli-launcher\\#automatic-selection)\r\n\r\nIf only one valid agent and provider type combination exists after filtering, the launcher skips the menu and launches the agent immediately.\r\n\r\n### [What happens at launch](https://tailscale.com/docs/aperture/cli-launcher\\#what-happens-at-launch)\r\n\r\nWhen you select an agent and provider type, the launcher:\r\n\r\n1. Sets the environment variables the agent requires for the selected provider type. Some environment variable values include path suffixes (for example, `/v1` or `/bedrock`) appended to the Aperture host URL.\r\n2. Writes temporary configuration files if the agent requires them.\r\n3. Appends skip-permissions flags if you've enabled full-auto mode.\r\n4. Saves your selection as the last-used combination.\r\n5. Hands the full terminal to the coding agent.\r\n\r\nWhen the agent exits, the launcher cleans up temporary files, re-checks the Aperture connection, and returns to the main menu.\r\n\r\n## [Supported agents](https://tailscale.com/docs/aperture/cli-launcher\\#supported-agents)\r\n\r\nThe launcher supports four coding agents. Each agent declares which provider types it can use, and the launcher filters the list based on your Aperture configuration.\r\n\r\n### [Claude Code](https://tailscale.com/docs/aperture/cli-launcher\\#claude-code)\r\n\r\n[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's terminal coding agent for Claude models. For setup instructions, refer to [Use Claude Code with Aperture](https://tailscale.com/docs/aperture/how-to/use-claude-code).\r\n\r\n- **Binary**: `claude`\r\n- **Provider types**: Anthropic API, AWS Bedrock, Google Vertex\r\n- **Install**: `curl -fsSL https://claude.ai/install.sh | bash`\r\n- **Full-auto flag**: `--dangerously-skip-permissions`\r\n\r\nThe launcher sets the following environment variables based on the selected provider type:\r\n\r\n| Provider type | Environment variables |\r\n| --- | --- |\r\n| Anthropic API | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` |\r\n| AWS Bedrock | `ANTHROPIC_BEDROCK_BASE_URL`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_SKIP_BEDROCK_AUTH` |\r\n| Google Vertex | `CLOUD_ML_REGION`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_SKIP_VERTEX_AUTH`, `ANTHROPIC_VERTEX_PROJECT_ID`, `ANTHROPIC_VERTEX_BASE_URL` |\r\n\r\nWhen providers include model information, the launcher also sets model-tier variables (`ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`) based on available models.\r\n\r\n### [Gemini CLI](https://tailscale.com/docs/aperture/cli-launcher\\#gemini-cli)\r\n\r\n[Gemini CLI](https://geminicli.com/) is Google's terminal coding agent for Gemini models.\r\n\r\n- **Binary**: `gemini`\r\n- **Provider types**: Google Vertex, Gemini API\r\n- **Install**: `npm install -g @google/gemini-cli`\r\n- **Full-auto flag**: `--yolo`\r\n\r\nThe launcher sets the following environment variables based on the selected provider type:\r\n\r\n| Provider type | Environment variables |\r\n| --- | --- |\r\n| Google Vertex | `GOOGLE_VERTEX_BASE_URL`, `GOOGLE_API_KEY` |\r\n| Gemini API | `GEMINI_API_KEY`, `GEMINI_BASE_URL` |\r\n\r\nThe launcher also sets `GEMINI_CLI_HOME` to point to the launcher-managed configuration directory.\r\n\r\nThe launcher writes a persistent settings file at `/aperture/gemini-home/.gemini/settings.json` with the authentication type for the selected provider type. This file persists between sessions. Refer to [Persistent state](https://tailscale.com/docs/aperture/cli-launcher#persistent-state) for `` values by operating system.\r\n\r\n### [OpenCode](https://tailscale.com/docs/aperture/cli-launcher\\#opencode)\r\n\r\n[OpenCode](https://opencode.ai/) is a terminal coding agent that supports multiple AI providers. For setup instructions, refer to [Use OpenCode with Aperture](https://tailscale.com/docs/aperture/how-to/use-opencode).\r\n\r\n- **Binary**: `opencode`\r\n- **Provider types**: Anthropic API, AWS Bedrock, Google Vertex, OpenAI Compatible\r\n- **Install**: `curl -fsSL https://opencode.ai/install | bash`\r\n\r\nThe launcher sets the following environment variables for OpenCode:\r\n\r\n| Provider type | Environment variables |\r\n| --- | --- |\r\n| Anthropic API | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` |\r\n| AWS Bedrock | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` |\r\n| Google Vertex | `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` |\r\n| OpenAI Compatible | `OPENAI_API_KEY`, `OPENAI_BASE_URL` |\r\n\r\nFor the Anthropic API provider type, the launcher sets `ANTHROPIC_BASE_URL` to the Aperture proxy's `/bedrock` path.\r\n\r\nThe launcher also sets `OPENCODE_CONFIG` to point to the launcher-managed configuration file.\r\n\r\nThe launcher writes a temporary configuration file at `~/.opencode/tmp_aperture_config.json` and deletes it when the agent exits.\r\n\r\n### [OpenAI Codex](https://tailscale.com/docs/aperture/cli-launcher\\#openai-codex)\r\n\r\n[OpenAI Codex](https://github.com/openai/codex) is OpenAI's terminal coding agent. For setup instructions, refer to [Use Codex with Aperture](https://tailscale.com/docs/aperture/how-to/use-codex).\r\n\r\n- **Binary**: `codex`\r\n- **Provider types**: OpenAI Compatible\r\n- **Install**: `npm install -g @openai/codex`\r\n- **Full-auto flag**: `--full-auto`\r\n\r\nThe launcher sets the following environment variables for Codex:\r\n\r\n| Provider type | Environment variables |\r\n| --- | --- |\r\n| OpenAI Compatible | `OPENAI_BASE_URL`, `OPENAI_API_KEY` |\r\n\r\nThe launcher also sets `CODEX_HOME` to point to the launcher-managed configuration directory.\r\n\r\nThe launcher writes a persistent auth file at `/aperture/codex-home/auth.json` to prevent Codex from prompting for interactive login on first run. Refer to [Persistent state](https://tailscale.com/docs/aperture/cli-launcher#persistent-state) for `` values by operating system.\r\n\r\n## [Configure settings](https://tailscale.com/docs/aperture/cli-launcher\\#configure-settings)\r\n\r\nPress `s` from the main menu to open the settings screen.\r\n\r\n### [Manage Aperture endpoints](https://tailscale.com/docs/aperture/cli-launcher\\#manage-aperture-endpoints)\r\n\r\nAdd and remove Aperture proxy URLs. The active endpoint is the host the launcher connects to on startup.\r\n\r\n1. Select **Aperture Endpoints** from the settings menu.\r\n2. To add a new endpoint, select the add option and enter the URL.\r\n3. To switch to a different endpoint, select it from the list.\r\n4. To delete an endpoint, highlight it and press `d` or `Delete`.\r\n\r\n### [Full-auto mode](https://tailscale.com/docs/aperture/cli-launcher\\#full-auto-mode)\r\n\r\nFull-auto mode (labeled **YOLO mode** in the settings menu) appends skip-permissions flags when launching agents. When enabled, agents run without asking for confirmation before executing commands or making changes.\r\n\r\nEach agent uses its own flag:\r\n\r\n| Agent | Flag |\r\n| --- | --- |\r\n| Claude Code | `--dangerously-skip-permissions` |\r\n| Gemini CLI | `--yolo` |\r\n| OpenAI Codex | `--full-auto` |\r\n\r\nTo toggle full-auto mode:\r\n\r\n1. Select **YOLO mode** from the settings menu.\r\n2. Toggle the setting on or off.\r\n\r\nThe setting persists across sessions.\r\n\r\nFull-auto mode grants agents broad permissions to execute commands and modify files without confirmation.\r\n\r\n### [Install and uninstall agents](https://tailscale.com/docs/aperture/cli-launcher\\#install-and-uninstall-agents)\r\n\r\nTo install a coding agent:\r\n\r\n1. Press `i` from the main menu, or select an agent marked as not installed.\r\n2. The launcher displays the install command for the selected agent. Run the command in a separate terminal.\r\n3. After installation, return to the launcher. The agent appears in the main menu on the next refresh.\r\n\r\nTo uninstall an agent:\r\n\r\n1. Open settings and select **Uninstall**.\r\n2. Select the agent to remove.\r\n3. Confirm the uninstall.\r\n\r\n## [Keyboard shortcuts](https://tailscale.com/docs/aperture/cli-launcher\\#keyboard-shortcuts)\r\n\r\nThe following keyboard shortcuts are available in the launcher:\r\n\r\n| Key | Action |\r\n| --- | --- |\r\n| `Up`/`Down` or `j`/`k` | Move cursor |\r\n| `Enter` or number key | Select item |\r\n| `s` | Open settings |\r\n| `i` | Install agents |\r\n| `a` | Add endpoint (in endpoints menu) |\r\n| `d` or `Delete` | Delete endpoint (in endpoints menu) |\r\n| `Esc` | Go back |\r\n| `q` | Quit |\r\n| `Ctrl+C` | Quit from any screen |\r\n\r\n## [Persistent state](https://tailscale.com/docs/aperture/cli-launcher\\#persistent-state)\r\n\r\nThe launcher stores settings and state in the OS default configuration directory under `aperture/`:\r\n\r\n- **macOS**: `~/Library/Application Support/aperture/`\r\n- **Linux**: `~/.config/aperture/`\r\n\r\n| File | Purpose |\r\n| --- | --- |\r\n| `settings.json` | Aperture endpoint URLs and full-auto mode preference |\r\n| `launcher.json` | Last-used agent and provider type combination |\r\n\r\nThe launcher creates these files automatically on first use.\r\n\r\n## [Troubleshoot the launcher](https://tailscale.com/docs/aperture/cli-launcher\\#troubleshoot-the-launcher)\r\n\r\nIf the launcher doesn't behave as expected, check the following common issues. For general Aperture issues, refer to [Troubleshooting Aperture](https://tailscale.com/docs/aperture/troubleshooting).\r\n\r\n### [Aperture host unreachable](https://tailscale.com/docs/aperture/cli-launcher\\#aperture-host-unreachable)\r\n\r\nIf the launcher can't connect to the Aperture host during the preflight check:\r\n\r\n- Verify the Aperture proxy is running and accessible from your device.\r\n- Confirm the host URL is correct. The default is `http://ai`.\r\n- Check your network connection, firewall rules, and tailnet policy file rules.\r\n\r\nThe launcher prompts you to enter a different URL if the configured host is unreachable.\r\n\r\n### [Agent binary not found](https://tailscale.com/docs/aperture/cli-launcher\\#agent-binary-not-found)\r\n\r\nIf a coding agent doesn't appear in the main menu:\r\n\r\n- Verify the agent binary is installed by running `which ` (for example, `which claude`).\r\n- Confirm the binary is in your `$PATH`, or in one of the directories the launcher checks: `~/.local/bin`, `~/bin`, or `~/.npm-global/bin`. The launcher finds binaries in system directories such as `/usr/local/bin` or `/opt/homebrew/bin` through your `$PATH`.\r\n- Press `i` from the main menu to access install commands for each agent.\r\n\r\n### [No compatible provider types available](https://tailscale.com/docs/aperture/cli-launcher\\#no-compatible-provider-types-available)\r\n\r\nIf a coding agent appears but offers no provider type options:\r\n\r\n- Verify that your Aperture proxy has providers configured with the API types the agent requires. For example, Claude Code requires at least one provider with Anthropic Messages API, Bedrock Model Invoke, or Google Vertex Raw Predict compatibility.\r\n- Check the [Aperture dashboard](https://tailscale.com/docs/aperture/reference/dashboard) to confirm provider configuration.\r\n\r\n### [Agent exits immediately](https://tailscale.com/docs/aperture/cli-launcher\\#agent-exits-immediately)\r\n\r\nIf a coding agent launches but exits immediately:\r\n\r\n- Run the launcher with the `-debug` flag to display the environment variables the launcher sets before launch:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\naperture -debug\r\n```\r\n\r\n- Check the agent's own logs for error messages.\r\n\r\n- Verify the Aperture proxy forwards requests correctly for the selected provider type.\r\n\r\n\r\n### [Conflicting environment variables in Claude Code settings](https://tailscale.com/docs/aperture/cli-launcher\\#conflicting-environment-variables-in-claude-code-settings)\r\n\r\nIf the launcher reports conflicting environment variables when launching Claude Code:\r\n\r\n- Open `~/.claude/settings.json` and check the `env` section.\r\n- Remove any variables that the launcher manages automatically, such as `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_USE_BEDROCK`, or `CLAUDE_CODE_SKIP_BEDROCK_AUTH`.\r\n- The launcher sets these variables for you based on the selected provider type.\r\n\r\n## [Command-line reference](https://tailscale.com/docs/aperture/cli-launcher\\#command-line-reference)\r\n\r\nThe launcher accepts the following flags:\r\n\r\n| Flag | Default | Description |\r\n| --- | --- | --- |\r\n| `-version` | `false` | Print version and exit |\r\n| `-debug` | `false` | Display environment variables before launching an agent |\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

CLI launcher reference

\n

Last validated: Apr 9, 2026

\n

Aperture by Tailscaleis currently in alpha.

\n

The Aperture launcher (aperture-cli) is a command-line interface (CLI) that configures and runs coding agents pre-connected to your Aperture proxy. It handles environment variables, configuration files, and provider type selection automatically, so you can start a coding session without editing configuration by hand.

\n

This page is part of the Aperture reference documentation.

\n

Prerequisites

\n

Before you use the launcher, confirm you have the following:

\n
    \n
  • A running Aperture proxy with at least one configured provider.
    • \n
  • Network access to the Aperture host URL (default: http://ai).
    • \n
  • At least one supported coding agent installed on your device. If you don't have one, the launcher provides install commands for each agent.
    • \n
  • Go 1.26 or later installed on the device you plan to install the aperture-cli on.
    • \n
\n

Install the launcher

\n

You can install the Aperture launcher using go install or by building the launcher from the Aperture repository on GitHub. These instructions cover using go install.

\n
    \n
  1. Install the aperture-cli using go install:
    2. \n
\n
go install github.com/tailscale/aperture-cli/cmd/aperture@latest\n
\n
    \n
  1. Start the aperture-cli launcher:
    2. \n
\n
aperture\n
\n

Connect to Aperture

\n

The launcher connects to your Aperture proxy on startup and verifies your provider configuration.

\n
    \n
  1. Run the launcher:
    2. \n
\n
aperture\n
\n

By default, the launcher connects to http://ai. To use a different host, open the settings menu and add or select an endpoint under Aperture Endpoints. The launcher persists your endpoint selection in settings.json.

\n
    \n
  1. Wait for the preflight check to complete.
    2. \n
\n

The launcher queries the Aperture proxy for its list of configured providers and their API compatibility. If the host is unreachable, the launcher prompts you to enter a different URL.

\n
    \n
  1. After a successful connection, the launcher displays the main menu with your available coding agents.
    2. \n
\n

The launcher saves the connected host to your settings and uses it automatically on the next launch.

\n

Manage multiple endpoints

\n

You can configure multiple Aperture proxy URLs and switch between them.

\n
    \n
  1. \n

    From the main menu, press s to open settings.

    \n
    2. \n
  2. \n

    Select Aperture Endpoints.

    \n
    3. \n
  3. \n

    Add or remove endpoints. Select an endpoint to make it the active host. The launcher uses the active endpoint on startup.

    \n
    4. \n
\n

To delete an endpoint, highlight it and press d.

\n

Launch a coding agent

\n

After the launcher connects to Aperture, select a coding agent and provider type to start a coding session.

\n

Select an agent

\n

The main menu lists all coding agents that the launcher detected on your device. Agents without an installed binary do not appear.

\n
Connected to http://ai (3 providers)\r\n\r\nWhich editor do you want to use?\r\n\r\n  [0] Last Used: Claude Code - Google Vertex\r\n  [1] Claude Code\r\n  [2] Gemini CLI\r\n  [3] OpenCode\r\n\r\n  [i] Install agents\r\n  [s] Settings\r\n  [q] Quit\r\n\r\nSelection (default: 0):\n
\n

The [0] Last Used shortcut launches the same agent and provider type combination from your previous session. Press 0 or Enter to relaunch it.

\n

If an agent you expect is missing from the list, the launcher couldn't find its binary. Refer to the troubleshooting section for resolution steps.

\n

Select a provider type

\n

After selecting an agent, choose a provider type. The launcher displays only provider types that are compatible with your configured Aperture providers.

\n

For example, if no provider in your Aperture configuration supports the Amazon Web Services (AWS) Bedrock API, the launcher hides the Bedrock option from the Claude Code provider type list.

\n

Automatic selection

\n

If only one valid agent and provider type combination exists after filtering, the launcher skips the menu and launches the agent immediately.

\n

What happens at launch

\n

When you select an agent and provider type, the launcher:

\n
    \n
  1. Sets the environment variables the agent requires for the selected provider type. Some environment variable values include path suffixes (for example, /v1 or /bedrock) appended to the Aperture host URL.
    2. \n
  2. Writes temporary configuration files if the agent requires them.
    3. \n
  3. Appends skip-permissions flags if you've enabled full-auto mode.
    4. \n
  4. Saves your selection as the last-used combination.
    5. \n
  5. Hands the full terminal to the coding agent.
    6. \n
\n

When the agent exits, the launcher cleans up temporary files, re-checks the Aperture connection, and returns to the main menu.

\n

Supported agents

\n

The launcher supports four coding agents. Each agent declares which provider types it can use, and the launcher filters the list based on your Aperture configuration.

\n

Claude Code

\n

Claude Code is Anthropic's terminal coding agent for Claude models. For setup instructions, refer to Use Claude Code with Aperture.

\n
    \n
  • Binary: claude
    • \n
  • Provider types: Anthropic API, AWS Bedrock, Google Vertex
    • \n
  • Install: curl -fsSL https://claude.ai/install.sh | bash
    • \n
  • Full-auto flag: --dangerously-skip-permissions
    • \n
\n

The launcher sets the following environment variables based on the selected provider type:

\n

| Provider type | Environment variables |\r\n| --- | --- |\r\n| Anthropic API | ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN |\r\n| AWS Bedrock | ANTHROPIC_BEDROCK_BASE_URL, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_SKIP_BEDROCK_AUTH |\r\n| Google Vertex | CLOUD_ML_REGION, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_SKIP_VERTEX_AUTH, ANTHROPIC_VERTEX_PROJECT_ID, ANTHROPIC_VERTEX_BASE_URL |

\n

When providers include model information, the launcher also sets model-tier variables (ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL) based on available models.

\n

Gemini CLI

\n

Gemini CLI is Google's terminal coding agent for Gemini models.

\n
    \n
  • Binary: gemini
    • \n
  • Provider types: Google Vertex, Gemini API
    • \n
  • Install: npm install -g @google/gemini-cli
    • \n
  • Full-auto flag: --yolo
    • \n
\n

The launcher sets the following environment variables based on the selected provider type:

\n

| Provider type | Environment variables |\r\n| --- | --- |\r\n| Google Vertex | GOOGLE_VERTEX_BASE_URL, GOOGLE_API_KEY |\r\n| Gemini API | GEMINI_API_KEY, GEMINI_BASE_URL |

\n

The launcher also sets GEMINI_CLI_HOME to point to the launcher-managed configuration directory.

\n

The launcher writes a persistent settings file at <config-dir>/aperture/gemini-home/.gemini/settings.json with the authentication type for the selected provider type. This file persists between sessions. Refer to Persistent state for <config-dir> values by operating system.

\n

OpenCode

\n

OpenCode is a terminal coding agent that supports multiple AI providers. For setup instructions, refer to Use OpenCode with Aperture.

\n
    \n
  • Binary: opencode
    • \n
  • Provider types: Anthropic API, AWS Bedrock, Google Vertex, OpenAI Compatible
    • \n
  • Install: curl -fsSL https://opencode.ai/install | bash
    • \n
\n

The launcher sets the following environment variables for OpenCode:

\n

| Provider type | Environment variables |\r\n| --- | --- |\r\n| Anthropic API | ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN |\r\n| AWS Bedrock | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION |\r\n| Google Vertex | GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION |\r\n| OpenAI Compatible | OPENAI_API_KEY, OPENAI_BASE_URL |

\n

For the Anthropic API provider type, the launcher sets ANTHROPIC_BASE_URL to the Aperture proxy's /bedrock path.

\n

The launcher also sets OPENCODE_CONFIG to point to the launcher-managed configuration file.

\n

The launcher writes a temporary configuration file at ~/.opencode/tmp_aperture_config.json and deletes it when the agent exits.

\n

OpenAI Codex

\n

OpenAI Codex is OpenAI's terminal coding agent. For setup instructions, refer to Use Codex with Aperture.

\n
    \n
  • Binary: codex
    • \n
  • Provider types: OpenAI Compatible
    • \n
  • Install: npm install -g @openai/codex
    • \n
  • Full-auto flag: --full-auto
    • \n
\n

The launcher sets the following environment variables for Codex:

\n

| Provider type | Environment variables |\r\n| --- | --- |\r\n| OpenAI Compatible | OPENAI_BASE_URL, OPENAI_API_KEY |

\n

The launcher also sets CODEX_HOME to point to the launcher-managed configuration directory.

\n

The launcher writes a persistent auth file at <config-dir>/aperture/codex-home/auth.json to prevent Codex from prompting for interactive login on first run. Refer to Persistent state for <config-dir> values by operating system.

\n

Configure settings

\n

Press s from the main menu to open the settings screen.

\n

Manage Aperture endpoints

\n

Add and remove Aperture proxy URLs. The active endpoint is the host the launcher connects to on startup.

\n
    \n
  1. Select Aperture Endpoints from the settings menu.
    2. \n
  2. To add a new endpoint, select the add option and enter the URL.
    3. \n
  3. To switch to a different endpoint, select it from the list.
    4. \n
  4. To delete an endpoint, highlight it and press d or Delete.
    5. \n
\n

Full-auto mode

\n

Full-auto mode (labeled YOLO mode in the settings menu) appends skip-permissions flags when launching agents. When enabled, agents run without asking for confirmation before executing commands or making changes.

\n

Each agent uses its own flag:

\n

| Agent | Flag |\r\n| --- | --- |\r\n| Claude Code | --dangerously-skip-permissions |\r\n| Gemini CLI | --yolo |\r\n| OpenAI Codex | --full-auto |

\n

To toggle full-auto mode:

\n
    \n
  1. Select YOLO mode from the settings menu.
    2. \n
  2. Toggle the setting on or off.
    3. \n
\n

The setting persists across sessions.

\n

Full-auto mode grants agents broad permissions to execute commands and modify files without confirmation.

\n

Install and uninstall agents

\n

To install a coding agent:

\n
    \n
  1. Press i from the main menu, or select an agent marked as not installed.
    2. \n
  2. The launcher displays the install command for the selected agent. Run the command in a separate terminal.
    3. \n
  3. After installation, return to the launcher. The agent appears in the main menu on the next refresh.
    4. \n
\n

To uninstall an agent:

\n
    \n
  1. Open settings and select Uninstall.
    2. \n
  2. Select the agent to remove.
    3. \n
  3. Confirm the uninstall.
    4. \n
\n

Keyboard shortcuts

\n

The following keyboard shortcuts are available in the launcher:

\n

| Key | Action |\r\n| --- | --- |\r\n| Up/Down or j/k | Move cursor |\r\n| Enter or number key | Select item |\r\n| s | Open settings |\r\n| i | Install agents |\r\n| a | Add endpoint (in endpoints menu) |\r\n| d or Delete | Delete endpoint (in endpoints menu) |\r\n| Esc | Go back |\r\n| q | Quit |\r\n| Ctrl+C | Quit from any screen |

\n

Persistent state

\n

The launcher stores settings and state in the OS default configuration directory under aperture/:

\n
    \n
  • macOS: ~/Library/Application Support/aperture/
    • \n
  • Linux: ~/.config/aperture/
    • \n
\n

| File | Purpose |\r\n| --- | --- |\r\n| settings.json | Aperture endpoint URLs and full-auto mode preference |\r\n| launcher.json | Last-used agent and provider type combination |

\n

The launcher creates these files automatically on first use.

\n

Troubleshoot the launcher

\n

If the launcher doesn't behave as expected, check the following common issues. For general Aperture issues, refer to Troubleshooting Aperture.

\n

Aperture host unreachable

\n

If the launcher can't connect to the Aperture host during the preflight check:

\n
    \n
  • Verify the Aperture proxy is running and accessible from your device.
    • \n
  • Confirm the host URL is correct. The default is http://ai.
    • \n
  • Check your network connection, firewall rules, and tailnet policy file rules.
    • \n
\n

The launcher prompts you to enter a different URL if the configured host is unreachable.

\n

Agent binary not found

\n

If a coding agent doesn't appear in the main menu:

\n
    \n
  • Verify the agent binary is installed by running which <binary-name> (for example, which claude).
    • \n
  • Confirm the binary is in your $PATH, or in one of the directories the launcher checks: ~/.local/bin, ~/bin, or ~/.npm-global/bin. The launcher finds binaries in system directories such as /usr/local/bin or /opt/homebrew/bin through your $PATH.
    • \n
  • Press i from the main menu to access install commands for each agent.
    • \n
\n

No compatible provider types available

\n

If a coding agent appears but offers no provider type options:

\n
    \n
  • Verify that your Aperture proxy has providers configured with the API types the agent requires. For example, Claude Code requires at least one provider with Anthropic Messages API, Bedrock Model Invoke, or Google Vertex Raw Predict compatibility.
    • \n
  • Check the Aperture dashboard to confirm provider configuration.
    • \n
\n

Agent exits immediately

\n

If a coding agent launches but exits immediately:

\n
    \n
  • Run the launcher with the -debug flag to display the environment variables the launcher sets before launch:
    • \n
\n
aperture -debug\n
\n
    \n
  • \n

    Check the agent's own logs for error messages.

    \n
    • \n
  • \n

    Verify the Aperture proxy forwards requests correctly for the selected provider type.

    \n
    • \n
\n

Conflicting environment variables in Claude Code settings

\n

If the launcher reports conflicting environment variables when launching Claude Code:

\n
    \n
  • Open ~/.claude/settings.json and check the env section.
    • \n
  • Remove any variables that the launcher manages automatically, such as ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK, or CLAUDE_CODE_SKIP_BEDROCK_AUTH.
    • \n
  • The launcher sets these variables for you based on the selected provider type.
    • \n
\n

Command-line reference

\n

The launcher accepts the following flags:

\n

| Flag | Default | Description |\r\n| --- | --- | --- |\r\n| -version | false | Print version and exit |\r\n| -debug | false | Display environment variables before launching an agent |

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}