Commands & runtime behavior

This document explains what each ags command does and what side effects to expect.

CLI summary#

ags [command]
ags --agent <pi|claude|codex|gemini|opencode|shell> [--browser] [--tmux] [--stop-when-done] [--psp] [--psp-keep] [--yolo] [--root] [--lockdown] [--wayland-compositor-passthrough] [--defaults|-D] [--config PATH] [--add-dir PATH ...] -- [agent args...]

Subcommands:

• setup
• doctor
• update
• update-agents
• install
• uninstall
• create-aliases
• completions

Use ags --help for built-in help text.

Run mode (--agent ...)#

Example:

ags --agent pi
ags --agent claude -- --model sonnet
ags --agent claude --defaults -- --model opus
ags --agent pi --browser
ags --agent pi --tmux
ags --agent pi --psp
ags --agent claude --lockdown
ags --agent claude -d ~/code -d ~/Downloads

What happens on run#

1. Load and validate config.
2. Ensure embedded assets exist on disk (Containerfile, tmux.conf, and any needed staged guard assets).
3. If not running with --lockdown, resolve secrets from configured host environment, keyring, or trusted command sources. Command helpers run on the host before container startup.
4. If not running with --lockdown, ensure sandbox git config exists.
5. If not running with --lockdown, ensure dedicated SSH agent is running and keys are loaded.
6. If not running with --lockdown and requested, start browser sidecar (--browser).
7. If not running with --lockdown, start auth proxy (Unix socket + shim in per-run temp dir).
8. If not running with --lockdown and [host_ui].enabled = true, start host UI sidecar.
9. If not running with --lockdown and [clipboard].enabled = true, start clipboard bridge sidecar and mount shims.
10. If not running with --lockdown, start webview origin relay for sandbox-served app origins.
11. If not running with --lockdown and requested, start PSP sidecar (--psp).
12. If running with --lockdown, stage a sanitized per-run agent home/runtime for the selected agent.
13. Build launch plan (mounts/env/security/network/entrypoint).
14. For Pi/Claude runs with guards enabled, verify the sandbox image contains dcg and warn if it does not.
15. Ensure image exists (builds if missing), then run podman run.

Notes#

• Args after -- are passed directly to agent CLI.
• --defaults / -D prepends AGS-managed default passthrough args for the selected agent harness. Today that means Claude gets --strict-mcp-config --dangerously-skip-permissions, Gemini gets --yolo, and other agents currently add nothing.
• --add-dir <path> / -d <path> adds an extra same-path directory mount for the current run only; repeat it to add multiple directories.
• --yolo disables AGS-managed Pi/Claude guard integrations for that run. For Pi, the AGS guard extension sees AGS_GUARD_YOLO=1 and becomes a no-op; for Claude, AGS omits its PreToolUse guard hook wiring.
• --lockdown minimizes host exposure for the current run. It disables configured secrets and passthrough env, SSH agent wiring, sandbox git config, generic [[mount]] entries, [[tool]]-derived mounts/secrets, host bridges/sidecars (including config-enabled host UI for that run), and direct mounting of the selected agent home. Instead AGS stages a sanitized ephemeral home/runtime for the selected agent and discards prior/current session history artifacts when the run exits.
• In lockdown mode, --add-dir still works, network access stays enabled, and exact workspace/external git metadata mounts still work as usual.
• Incompatible with --browser, --psp, --psp-keep, --root, and --wayland-compositor-passthrough.
• Container runs with rootless user namespace (keep-id), dropped capabilities, and no-new-privileges.
• Agent host state normally comes from explicit [[agent_mount]] / [[mount]] entries; lockdown overrides that with staged per-run agent state.
• Agent processes run inside the container: localhost is container-local. Use host.containers.internal for host machine ports/services.
• Outside lockdown, runtime env vars are injected for discoverability: AGS_HOST_SERVICES_HOST and AGS_HOST_SERVICES_HINT.
• Outside lockdown, pi/claude/codex runs also inject a short host-service hint into prompt context.
• Outside lockdown, interactive launches print a one-line host-service reminder before the agent CLI starts.
• --tmux wraps the agent command in a tmux session inside the container. After the agent exits, an interactive shell remains available for inspection. Combine with --stop-when-done to exit immediately instead.
• --stop-when-done (requires --tmux) exits the container as soon as the agent process finishes instead of dropping to an interactive shell. Useful for batch/CI runs where you don't need post-task inspection.
• --wayland-compositor-passthrough mounts the real host Wayland compositor socket. This is broad desktop access and is separate from clipboard support; keep it off unless you intentionally need sandbox GUI clients to connect directly to the compositor.
• The sidecar/bridge notes below apply to normal runs; lockdown suppresses them.
• --psp enables podman-socket-proxy mode. AGS spawns a psp sidecar process with a per-run Unix socket, waits for it to be ready, then mounts the socket into the container and sets DOCKER_HOST so Docker/Testcontainers clients route through PSP. On exit, AGS sends SIGTERM to allow PSP to clean up any containers it created, then falls back to SIGKILL after 5 seconds. PSP enforces policy-gated access to the host Podman API (deny-by-default, image allowlists, bind mount restrictions). The psp binary must be on PATH or configured via [psp].binary in config.toml. PSP picks up its own policy files (global ~/.config/psp/config.json and project-local .psp.json). A stable session identifier (PSP_SESSION_ID) is injected into the container environment for tools that support the x-psp-session-id header.
• --psp-keep tells PSP to retain containers it created when the session ends (sets PSP_KEEP_ON_FAILURE=true). Useful for debugging failed test runs. Stale containers will be cleaned up automatically on the next PSP start (startup sweep).
• The auth proxy starts automatically on every run. Inside the container, $BROWSER points to the auth-proxy-shim. When agent code opens a URL (e.g. OAuth login), the shim sends it to the host proxy over a Unix socket. The host prompts the user through the shared AGS dialog renderer: a branded Glimpse host-UI dialog when [host_ui] is enabled, otherwise zenity/kdialog fallback. Standard URLs get Open / Cancel. If the target itself is http://localhost:<port>/... or http://127.0.0.1:<port>/... and the AGS webview relay is available, the dialog also offers Proxy, which rewrites the URL through the same dedicated host-port relay used for sandbox-served Glimpse apps. When AGS host UI is enabled, Proxy prefers opening that relayed URL in a host-owned Glimpse window; otherwise it falls back to the normal host browser. For OAuth flows with a localhost callback, the host proxy captures the browser redirect and relays it back into the container. If no dialog renderer is available, all URL-open requests are auto-denied. The proxy shuts down and cleans up its temp directory when the container exits. Domains listed in [auth_proxy].auto_allow_domains skip the dialog.
• If [host_ui].enabled = true, AGS starts a per-session host UI service and mounts /run/ags-host-ui into the sandbox. The host owns the actual Glimpse window; sandboxed code only sees the socket-backed client API. For user-facing setup and troubleshooting, see docs/GLIMPSE.md.
• If [clipboard].enabled = true, AGS starts a per-session clipboard bridge, mounts /run/ags-clipboard, shadows wl-paste/wl-copy with shims in /home/dev/.local/bin, and sets XDG_SESSION_TYPE=wayland so Pi's Ctrl-V image paste uses the shim path. Pi Ctrl-V image paste reads host clipboard through this bridge; by default the host prompts once and can allow reads for [clipboard].approval_seconds. /copy-style flows write through it when mode = "readwrite".
• The webview origin relay also starts automatically. It exposes AGS_WEBVIEW_RELAY_SOCKET and AGS_WEBVIEW_RELAY_UPSTREAM_SOCKET inside the sandbox plus a helper command ags-webview-url <port> [base_path]. Use it when a host-owned webview must load a temporary HTTP app server running on 127.0.0.1:<port> inside the container. The helper returns a dedicated host origin for that app, but Glimpse-based packages should normally just pass their ordinary localhost URL to glimpseui and let Glimpse resolve it automatically.
• Postgres quick-connect from host into sandbox shell:
  • ags --agent shell -- -lc 'PGPASSWORD="${PGPASSWORD:-postgres}" psql -h "${AGS_HOST_SERVICES_HOST}" -p "${PGPORT:-5432}" -U "${PGUSER:-postgres}" "${PGDATABASE:-postgres}"'

ags setup#

Initial bootstrap.

What it does#

• Generates missing SSH keys:
  • auth key
  • signing key
• Prints public keys (for GitHub SSH + signing setup).
• Ensures Pi guard/settings assets exist in the host path mounted to /home/dev/.pi.
• If secret-tool exists, prompts for optional interactive secret storage.

Typical usage#

ags setup

ags doctor#

Health checks for your environment and config.

Checks include#

• Required/optional host tooling
• Required config/assets presence
• Tool binaries and configured mounts
• Image presence
• Whether bundled dcg is available inside the sandbox image
• SSH keys and dedicated ssh-agent state
• Secret source availability
• Session directory/writeability checks
• Browser setup checks (if enabled)

Typical usage#

ags doctor

ags update-image#

Rebuilds sandbox image from configured Containerfile and refreshes bundled sandbox tools:

• br from beads_rust releases
• dcg from destructive_command_guard releases

ags update-image
ags update-image --keep-existing

• Resolves the newest stable release that provides the required archive and checksum for the image architecture
• Skips incomplete or platform-specific newer releases with a warning instead of failing on a missing asset
• Verifies release checksums during image build and refuses releases without a checksum asset
• Removes the previously tagged sandbox image after the new build succeeds, unless a container still references it
• Referenced previous images are retained with a warning listing the blocking container IDs
• --keep-existing keeps the previous image for manual rollback/debugging
• Does not update agent CLIs installed in persistent volumes

ags update remains as a deprecated alias for ags update-image.

Version check (inside sandbox):

ags --agent shell -- -lc 'br --version && dcg --version'

Use ags update-agents next if needed.

ags update-agents#

Installs/updates agent CLIs in persistent volumes using a temporary container.

ags update-agents

What it updates#

• Pi package (pi_spec), removing the legacy Pi package first to avoid stale pi binaries
• Codex (@openai/codex)
• Gemini (@google/gemini-cli)
• Opencode (opencode-ai)
• Claude install/update in dedicated volume

Settings come from [update] in config.

Security hardening and runtime hygiene:

• pnpm installs run with ignore-scripts=true.
• pnpm uses a stable store under /usr/local/pnpm/.store.
• update-agents removes stale pnpm self-update shims from /usr/local/pnpm so sandbox pnpm resolves to the image-provided pnpm binary.
• update-agents removes old npm-global agent shims so they cannot shadow the pnpm-managed AGS agents.

ags install#

Installs baseline assets and optional ags self-link.

ags install
ags install --link-self
ags install --link-self --force

What it writes#

• ~/.config/ags/Containerfile
• ~/.config/ags/tmux.conf
• <agent-dir>/extensions/guard.ts
• <agent-dir>/settings.json (if missing)

By default <agent-dir> is ~/.config/ags/pi. It can be overridden with AGS_AGENT_DIR.

Flags#

• --link-self : create ~/.local/bin/ags symlink to current executable
• --force : replace existing link/file where applicable
• --add-agent-mounts : append default required [[agent_mount]] entries to ~/.config/ags/config.toml

ags uninstall#

Currently a reserved/no-op command.

ags uninstall

ags create-aliases#

Generates managed wrappers and/or shell alias blocks.

ags create-aliases
ags create-aliases --mode both --shell fish
ags create-aliases --mode wrappers --force

Flags#

• --mode wrappers|aliases|both (default: wrappers)
• --shell fish|zsh|bash (autodetect if omitted)
• --force (replace existing non-managed targets)

Behavior#

• Wrappers go to ~/.local/bin/.
• Managed shortcuts use --defaults where applicable so direct launches and generated wrappers stay in sync.
• Alias blocks are inserted/updated in shell rc files:
  • fish: ~/.config/fish/config.fish
  • zsh: ~/.zshrc
  • bash: ~/.bashrc

Managed alias blocks are clearly delimited so future runs can update them safely.

ags completions#

Prints shell completion scripts to stdout.

ags completions --shell bash
ags completions --shell zsh
ags completions --shell fish

Typical install paths#

# bash
ags completions --shell bash > ~/.local/share/bash-completion/completions/ags

# zsh
ags completions --shell zsh > ~/.zfunc/_ags

# fish
ags completions --shell fish > ~/.config/fish/completions/ags.fish

Makefile shortcuts#

Equivalent convenience targets:

• make setup
• make doctor
• make update
• make update-agents
• make run
• make run-browser
• make install
• make install-self
• make uninstall
• make aliases