Supported agents | Installation | Usage | Development | Contributing
Warning
This repository is alpha software. It is under active development and may change significantly without notice.
A CLI launcher for coding agents preconfigured to work with Aperture. It manages installation, configuration and environment variables that make using multiple providers and models very easy.
go install github.com/tailscale/aperture-cli/cmd/aperture@latestOr build from source:
make buildapertureOn first run, aperture will attempt to connect to http://ai. If it cannot reach that host, it will prompt you to configure an Aperture endpoint.
Bridge mode lets Aperture CLI reach an Aperture endpoint through an embedded Tailscale node. Only the Aperture CLI proxy appears on the tailnet; the rest of the machine does not need the full Tailscale client installed or connected to that tailnet.
This is useful on machines where installing Tailscale is not practical, where Aperture needs to work alongside another VPN, or where you need to switch tailnets while continuing to use a single Aperture instance.
To use bridge mode:
- Press
con the agent menu forChange connection(the same screen asSettings, thenAperture Endpoints). - Choose
Add a connection, thenBridge, then an existing bridge orAdd Bridge. - Authorize the bridge. Aperture CLI opens your browser at the Tailscale login link; if it cannot, the link stays on screen to open by hand. No URL is asked for: the bridge looks for Aperture at
http://ai, the same location a direct connection starts from. - Aperture CLI verifies
/v1/models, makes the endpoint active, and returns to the agent menu.
If your Aperture answers on a different hostname, type it on the connect screen while the default is being tried. That cancels the attempt and connects to what you typed. Esc abandons the attempt and leaves your current endpoint alone.
Change connection lists everything this launcher can reach: each saved endpoint, and each bridge that has no endpoint yet, labelled with the tailnet it reaches. That is the screen to use when the launcher connected on its own and you wanted the other bridge.
Selecting a row opens it. From there you can connect to it, change its URL, switch its tailnet, or remove it.
http://ai can answer and still be the wrong Aperture, which is what happens when the bridge joins a tailnet that already has a host called ai. Change URL points the connection somewhere else; it keeps the bridge it is reached through and reconnects.
A bridge is on one tailnet at a time. Switch tailnet logs it out, which removes its node from that tailnet, then prints a new login link: open it and pick the tailnet you want. Use a second bridge instead if you want to keep both logins and choose between them.
If verification fails, the endpoint remains configured for retry or editing, and any previous working endpoint remains active.
| Flag | Environment | Description |
|---|---|---|
-version |
Print build version and exit | |
-debug |
Print environment variables set before launching the agent | |
-endpoint |
APERTURE_ENDPOINT |
Aperture URL to open on, instead of the saved one |
-bridge |
APERTURE_BRIDGE |
Connect through the bridge with this name, creating it if there is none |
A flag beats its environment variable, so a one-off run can override whatever
the shell was started with. -bridge on its own starts at the well-known
location, the same guess the connection picker makes:
aperture -bridge work # http://ai over the "work" bridge
aperture -bridge work -endpoint aperture.example.com # that URL over the "work" bridge
aperture -endpoint aperture.example.com # direct, no bridgeNeither is made the saved active endpoint until the connection works, so an unreachable URL passed on the command line does not displace the one that does work.
make build # build ./aperture
make test # run tests
make install # install to $GOPATH/bin
make clean # remove built binaryTo add a new coding agent, see docs/adding-a-client.md.