Aperture CLI
A launcher that starts Claude Code, Codex, Gemini CLI and other agents with Tailscale Aperture settings, with a bridge mode
- 90 ★ on the repository
- Last commit
Extended access
Why this level
- The launcher sets agent environments and sends their model requests through the chosen Aperture address, and a bridge registers a device in your tailnet.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/tailscale/aperture-cli/main/install.sh | shThe first README command installs `aperture` into `/usr/local/bin`, so read the script first. `APERTURE_INSTALL_DIR=$HOME/.local/bin` skips sudo.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The launcher sets agent environments and sends their model requests through the chosen Aperture address, and a bridge registers a device in your tailnet.
This is third-party code. Review the repository files before installing.
What it does
aperture installs and configures coding agents so they work through Aperture, a Tailscale service. The launcher sets environment variables and configuration itself, so a single `aperture` command opens an agent menu and `aperture codex --model openai/gpt-5-mini` starts the chosen agent with the right model. Claude Code, Gemini CLI, OpenCode, Codex, GitHub Copilot CLI, Hermes Agent, Oh My Pi, Pi and Claude Cowork are supported. On first run the launcher tries `http://ai` and, if that host is unreachable, asks for the Aperture address. Bridge mode connects the launcher to Aperture through an embedded Tailscale node: only the launcher proxy appears on the tailnet, and the full Tailscale client is not needed on the machine. Everything the TUI configures is also a command: `aperture bridge add`, `aperture endpoint add`, and `aperture serve` keeps a bridge on a fixed port, with a systemd unit example.
Who it is for. Teams that use Tailscale Aperture as their model access point and want to launch different agents with one setup.
Good fit when
- A developer switches between Claude Code and Codex and does not want to change keys and URLs by hand
- Tailscale cannot be installed in full on the machine, so a built-in bridge to Aperture is needed
- The Aperture address has to be pinned for clients through `aperture serve --bridge work`
- Launcher setup goes into a script, dotfile or systemd unit through the `endpoint` and `bridge` commands
Not a fit when
- Aperture is not used in the organization, and the launcher targets only it
- You need a stable release, as the author calls the repository alpha software with significant changes expected
- Running a single agent with its own settings is enough
Example request
Launch Codex through aperture with the openai/gpt-5-mini model and check that endpoint e1 respondsLimitations
The repository is marked alpha and may change significantly without notice. The launcher works only with Aperture: if `http://ai` answers but belongs to a different tailnet, change the address through `Change URL`. Each `aperture` process on a bridge registers as its own tailnet device, and a new device needs one login or a `TS_AUTHKEY` key. macOS builds are signed and notarized, but an archive downloaded in a browser may be blocked by Gatekeeper. The install script places the binary in `/usr/local/bin`.
How to disable. Delete the `aperture` binary from `/usr/local/bin` (or the directory from `APERTURE_INSTALL_DIR`) and remove bridges with `aperture bridge delete <name>`, which first logs the bridge machines out of the tailnet.
FAQ
How do I install aperture?
Run `curl -fsSL https://raw.githubusercontent.com/tailscale/aperture-cli/main/install.sh | sh`, which verifies the release checksum. `go install github.com/tailscale/aperture-cli/cmd/aperture@latest` also works.
How do I launch Codex through aperture?
Run `aperture codex --endpoint e1` or `aperture codex --model openai/gpt-5-mini`. The first unknown flag or `--` passes the rest to the agent verbatim.
What is bridge mode?
An embedded Tailscale node through which the launcher reaches Aperture. Only the launcher proxy appears on the tailnet, and the full Tailscale client is not needed on the machine.
How do I join the tailnet without a browser?
Set `TS_AUTHKEY` to a reusable key from the right tailnet. New devices authorize without a browser, and registered ones use stored credentials.
Which agents are supported?
Claude Code, Gemini CLI, OpenCode, Codex, GitHub Copilot CLI, Hermes Agent, Oh My Pi, Pi and Claude Cowork. Launch them by binary name, for example `aperture codex`.
Discussion
No questions or reviews yet.
Related
CLI toolsArcBox runs Claude Code in a disposable microVM on a Mac: its own kernel, an empty workspace and a start in about a second
Containarium: isolated boxes for AI agents
Containarium
A platform on your own server that gives each agent its own Linux box with SSH and MCP tools for commands and files
CLI that runs commands and AI agents in isolated microVMs that boot in under 125 ms and keeps API keys out of the sandbox itself.
A CLI that runs Claude Code and Codex in isolated Docker containers with a firewall, worktrees and a no-Dockerfile image.
AgentBox runs Claude Code, Codex and Open Code in separate virtual machines on your PC, a self-hosted server or a cloud.
Native macOS terminal with an MCP server and CLI: agents see panes, commands and output, and you grant permissions in one window
README in short
The README warns about alpha status, lists supported agents, gives install by script, Go and from source, and describes bridge mode, choosing and switching connections, concurrent sessions and the command line.