Launch coding agents with the Aperture CLI

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.

Prerequisites

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

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

Install the launcher

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.

1. Install the aperture-cli using go install:

   go install github.com/tailscale/aperture-cli/cmd/aperture@latest
   

2. Start the aperture-cli launcher:

   aperture
   

Connect to Aperture

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

1. Run the launcher:

   aperture
   

   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.

2. Wait for the preflight check to complete.

   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.

3. After a successful connection, the launcher displays the main menu with your available coding agents.

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

Manage multiple endpoints

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

1. From the main menu, press s to open settings.

2. Select Aperture Endpoints.

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

To delete an endpoint, highlight it and press d.

Launch a coding agent

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

Select an agent

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

Connected to http://ai (3 providers)

Which editor do you want to use?

  [0] Last Used: Claude Code - Google Vertex
  [1] Claude Code
  [2] Gemini CLI
  [3] OpenCode

  [i] Install agents
  [s] Settings
  [q] Quit

Selection (default: 0):

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

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.

Select a provider type

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

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.

Automatic selection

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

What happens at launch

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

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. Writes temporary configuration files if the agent requires them.
3. Appends skip-permissions flags if you've enabled full-auto mode.
4. Saves your selection as the last-used combination.
5. Hands the full terminal to the coding agent.

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

Supported agents

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.

Claude Code

Claude Code is Anthropic's terminal coding agent for Claude models.

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

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

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.

Gemini CLI

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

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

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

The launcher writes a persistent settings file at ~/.config/aperture/gemini-home/.gemini/settings.json with the authentication type for the selected provider type. This file persists between sessions.

OpenCode

OpenCode is a terminal coding agent that supports multiple AI providers.

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

The launcher sets the following environment variables for OpenCode:

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

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

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

OpenAI Codex

OpenAI Codex is OpenAI's terminal coding agent.

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

The launcher sets the following environment variables for Codex:

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

The launcher writes a persistent auth file at ~/.config/aperture/codex-home/auth.json to prevent Codex from prompting for interactive login on first run.

Configure settings

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

Manage Aperture endpoints

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

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

Full-auto mode

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.

Each agent uses its own flag:

To toggle full-auto mode:

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

The setting persists across sessions.

Install and uninstall agents

To install a coding agent:

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

To uninstall an agent:

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

Keyboard shortcuts

Persistent state

The launcher stores settings and state in ~/.config/aperture/.

The launcher creates these files automatically on first use.

Troubleshoot the launcher

If the launcher doesn't behave as expected, check the following common issues.

Aperture host unreachable

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

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

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

Agent binary not found

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

• Verify the agent binary is installed by running which <binary-name> (for example, which claude).
• 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.
• Press i from the main menu to access install commands for each agent.

No compatible provider types available

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

• 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.
• Check the Aperture admin dashboard to confirm provider configuration.

Agent exits immediately

If a coding agent launches but exits right away:

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

  aperture -debug
  

• Check the agent's own logs for error messages.

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

Conflicting environment variables in Claude Code settings

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

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

Command-line reference

The launcher accepts the following flags: