@aitty/cli

Reference command-line launcher for aitty browser terminal sessions.

Use it to run an interactive agent CLI in a local browser without writing a host application first. For SDK integrations, use @aitty/server and @aitty/browser directly.

Install

npm i -g @aitty/cli

Or run without global install:

npx @aitty/cli exec -- codex

Usage

aitty exec -- codex
aitty exec -- claude
aitty exec -- droid -r

List and stop local sessions started by aitty exec:

aitty list
aitty stop <id>
aitty stop all
aitty prune

Choose how the startup link is handled:

aitty exec --launch open -- codex
aitty exec --launch qr -- codex
aitty exec --launch copy -- codex
aitty exec --launch print -- codex

--launch auto is the default. In an interactive terminal it shows a startup menu; in scripts it keeps non-interactive behavior. --no-open remains a compatibility alias for --launch print.

Set startup options before the command:

aitty exec --cwd /path/to/project --theme dark -- codex
aitty exec --project my-app --label droid16 --title "Droid 16" -- droid16 -r

Expose the session to another device on the same LAN:

aitty exec --lan -- codex
aitty exec --lan --public-host 192.168.1.23 -- codex

Use a reverse proxy, gateway, or tunnel entrypoint:

aitty exec --public-origin https://agent.example.com -- codex

For many sessions behind one stable origin, run aitty gateway first:

aitty gateway --port 8910 --public-origin https://agent.example.com
aitty exec --public-origin https://agent.example.com -- codex
aitty exec --public-origin https://agent.example.com -- claude

Expose a temporary public HTTPS session with Cloudflare Quick Tunnel:

aitty exec --cloudflare -- codex

Use a Cloudflare named tunnel and Access-protected hostname through a fixed gateway. Start the gateway in one terminal:

aitty gateway \
  --port 14375 \
  --cloudflare \
  --cloudflare-tunnel aitty \
  --cloudflare-hostname aitty.example.com

Then start sessions from other terminals:

aitty exec \
  --public-origin https://aitty.example.com \
  -- codex

Quick Tunnel is useful for short-lived testing, but it does not provide Cloudflare Access authentication. Email, OTP, IdP, and group policies are configured in Cloudflare Zero Trust for a named tunnel hostname. See the full project guide: Cloudflare Tunnel and Zero Trust. For the complete command reference, see CLI usage.

Options

• --cwd <dir> sets the child process working directory.
• --port <port> binds a specific port from 0 to 65535; required for named Cloudflare tunnel modes.
• --host <host> binds a specific host. Non-loopback hosts require --lan.
• --lan binds 0.0.0.0 and prints a LAN-accessible URL.
• --public-host <host> sets the hostname/IP printed in the browser URL without changing the bind host.
• --public-origin <url> sets the full printed URL origin for reverse proxy, gateway, or tunnel integrations.
• --cloudflare exposes the session through a cloudflared tunnel. In exec, this uses Quick Tunnel unless --cloudflare-tunnel is set. In gateway, this starts a named tunnel.
• --cloudflare-bin <cmd> sets the cloudflared executable path or command name.
• --cloudflare-tunnel <name> runs a named Cloudflare Tunnel. It requires --port and --cloudflare-hostname.
• --cloudflare-hostname <host> sets the public hostname for the named tunnel. Protect this hostname with Cloudflare Access.
• --cloudflare-protocol <mode> sets named tunnel transport to http2, quic, or auto; default is http2.
• --buffer-size <bytes> changes replay buffer size from 1024 to 16777216.
• --project <name> sets the project segment in the browser session URL.
• --label <name> sets the label segment in the browser session URL.
• --title <text> sets the browser shell title.
• --subtitle <text> sets the browser shell subtitle.
• --theme <name> sets the initial shell data-theme.
• --font-size <px> sets the initial terminal font size from 11 to 24.
• --launch <mode> chooses startup behavior: menu, open, qr, copy, print, or auto.
• --no-open is a compatibility alias for --launch print.
• --verbose prints debug logs to stderr.
• --help and --version print CLI metadata.

Session Management

• aitty list and aitty ps print currently running local sessions.
• aitty stop <id> sends SIGTERM to the owning aitty exec process. Prefixes are accepted when unambiguous.
• aitty stop all stops every registered local session.
• aitty prune removes stale records for processes that are no longer alive.

Session records are stored in the current user's local state directory. They are best-effort metadata, not a daemon; if a process crashes, list and prune clean up stale records. On macOS and Linux, list also best-effort discovers unregistered aitty exec processes that were started before session management was available; those entries use a pid-<pid> id and can be stopped with aitty stop pid-<pid>.

Gateway

aitty gateway starts a fixed local reverse proxy for registered sessions. Use it when one stable public origin should serve many simultaneous /s/<project>/<session>?t=<token> session paths.

aitty gateway --port 8910 --public-origin https://aitty.example.com
aitty exec --public-origin https://aitty.example.com -- codex

For Cloudflare named tunnels, point the tunnel ingress at the gateway port and start sessions separately with the same public origin.

aitty exec --cloudflare-tunnel ... is still available for single-session named tunnel setups, but it requires --port because the Cloudflare ingress must target that exact local port. The gateway model is the recommended path for stable remote access.

Notes

• The CLI prints the tokenized session URL to stdout.
• Local sessions bind to loopback by default and use a *.localhost display URL with the same stable /s/<project>/<session> path.
• --lan exposes the tokenized PTY session to your network. Use it only on trusted networks.
• --launch qr uses --public-origin when provided. Without a public origin, it enables LAN binding so phones can scan a reachable URL.
• --cloudflare keeps the local server loopback-only while exposing a public HTTPS tunnel.
• Quick Tunnel URLs are public and temporary; use a named tunnel with Cloudflare Access for email/OTP or IdP authentication.
• Named tunnels default to http2 because it is more reliable on networks that block QUIC/UDP.
• Logs and runtime errors go to stderr.
• One invocation owns one PTY child and one local browser session.

License

Apache-2.0