agent/sandbox Documentation
Docs/Operate
Reference7 min readdocs/TROUBLESHOOTING.md

Troubleshooting

Diagnose common image, mount, terminal, SSH, browser, clipboard, and host-service problems.

View source Markdown

Start here:

bash
ags doctor

Most issues are visible in doctor output.

error: required mount source missing#

A required mount path in config does not exist.

Fix#

  • Create the path on host, or
  • mark mount as optional = true, or
  • set create = true (for paths safe to auto-create)

Container image missing or outdated#

Symptoms:

  • image-not-found errors
  • old runtime dependencies

Fix#

bash
ags update-image

Then if needed:

bash
ags update-agents

br / dcg missing inside container#

If bundled sandbox commands are missing or stale.

Fix#

bash
ags update-image
ags --agent shell -- -lc 'br --version && dcg --version'

ags update-image refreshes from upstream releases:

For each tool, AGS selects the newest stable release containing both the required archive and its checksum for the image architecture. If a newer release only publishes assets for other platforms, AGS warns and uses the newest compatible release instead.

Startup warning: dcg is missing and Pi/Claude guards will fail open#

Symptoms:

  • ags doctor reports bundled dcg missing inside the sandbox image
  • ags --agent pi or ags --agent claude prints a startup warning about dcg
  • Pi also shows an in-session warning that Bash classification will fail open

Fix#

bash
ags update-image
ags doctor
ags --agent shell -- -lc 'dcg --version'

If you intentionally want to bypass AGS guard layers for a single Pi/Claude run, use:

bash
ags --agent pi --yolo
ags --agent claude --yolo

psql missing inside container#

If psql is not found in sandbox shell.

Fix#

bash
ags update-image
ags --agent shell -- -lc 'psql --version'

tmux missing when using --tmux#

Symptoms:

  • ags --agent <name> --tmux fails with tmux: not found
  • or AGS prints a message telling you to rebuild the sandbox image

Cause:

  • your existing sandbox image was built before tmux support was added

Fix#

bash
ags update-image
ags --agent shell -- -lc 'tmux -V && test -f ~/.tmux.conf'

Glimpse falls back to Chromium / Chrome detection#

Symptoms:

  • logs mention No Chromium or Chrome installation found
  • sandboxed glimpseui code behaves like ordinary Chromium fallback mode instead of opening a host-owned window

Cause:

  • AGS host UI is disabled or misconfigured
  • your ags binary is stale
  • your sandbox image is stale
  • you are still using an old AGS session

Fix#

Verify your config has a real [host_ui] setup, then rebuild and restart:

bash
cargo build --release -p ags
ags update-image
ags doctor

Start a fresh session, then verify the runtime wiring:

bash
ags --agent shell -- -lc 'echo "$AGS_HOST_UI_SOCK"; echo "$GLIMPSE_BINARY_PATH"; ls -l /opt/ags/glimpse-shim'

Expected:

  • AGS_HOST_UI_SOCK=/run/ags-host-ui/host-ui.sock
  • GLIMPSE_BINARY_PATH=/opt/ags/glimpse-shim
  • /opt/ags/glimpse-shim exists

For a user-facing overview, see docs/GLIMPSE.md.

Pi Ctrl-V image paste or /copy clipboard actions fail#

Symptoms:

  • Pi Ctrl-V image paste reports no clipboard data or wl-paste errors
  • /copy reports clipboard failures from inside the sandbox
  • echo "$AGS_CLIPBOARD_SOCK" is empty

Cause:

  • [clipboard].enabled is false or mode = "off"
  • the AGS binary/session predates the clipboard bridge
  • host wl-paste/wl-copy is unavailable or cannot access your host clipboard
  • payload exceeded [clipboard].max_bytes
  • clipboard approval was denied or no dialog renderer was available

Fix#

Verify bridge wiring in a fresh session:

bash
ags --agent shell -- -lc 'echo "$AGS_CLIPBOARD_SOCK"; echo "$AGS_CLIPBOARD_MODE"; echo "$XDG_SESSION_TYPE"; command -v wl-paste; command -v wl-copy'

Expected:

  • AGS_CLIPBOARD_SOCK=/run/ags-clipboard/clipboard.sock
  • AGS_CLIPBOARD_MODE=read or readwrite
  • XDG_SESSION_TYPE=wayland
  • wl-paste/wl-copy resolve to /home/dev/.local/bin/...

If the bridge is intentionally disabled, enable it in config:

toml
[clipboard]
enabled = true
mode = "readwrite"
approval_required = true
approval_seconds = 300

Clipboard reads prompt on the host by default. Enable [host_ui] for the branded dark/light-aware dialog, or install zenity/kdialog for the fallback. If you intentionally want the old session-wide bridge behavior, set approval_required = false.

For raw GUI clients, do not rely on clipboard settings; use the explicit --wayland-compositor-passthrough flag only when you intentionally want broad desktop access.

SELinux alerts mentioning pasta and your source tree#

Symptoms:

  • host notifications or logs mention SELinux blocking pasta
  • messages refer to a directory like code or your repo path

Cause:

  • a previously relabeled bind mount left the wrong SELinux context on part of your worktree

Fix#

Restore labels on the affected tree:

bash
restorecon -RFv /home/$USER/code/agent-sandbox

If your repos live elsewhere, run restorecon on the appropriate parent path instead.

missing or unsuitable terminal: xterm-kitty in tmux#

Symptoms:

  • running tmux inside the sandbox fails with missing or unsuitable terminal: xterm-kitty

Cause:

  • your host terminal exports TERM=xterm-kitty
  • the sandbox image needs kitty terminfo entries available for tmux to start cleanly

Fix#

Rebuild the image so the sandbox includes kitty-terminfo:

bash
ags update-image
ags --agent shell -- -lc 'echo "$TERM" && tmux -V'

Temporary workaround if you need it before rebuilding:

bash
TERM=xterm-256color ags --agent shell

Cannot reach host service from agent (localhost confusion)#

Symptoms:

  • Service works on host but fails from inside agent/shell
  • curl http://localhost:<port> fails in sandbox

Cause:

  • Agent runs inside container, so localhost points to container itself.

Fix#

Use host gateway name instead:

bash
curl http://host.containers.internal:<port>

Example:

bash
ags --agent shell -- -lc 'curl http://host.containers.internal:3000/health'

You can verify runtime hint env vars too:

bash
ags --agent shell -- -lc 'echo "$AGS_HOST_SERVICES_HOST" && echo "$AGS_HOST_SERVICES_HINT"'

Agent CLI missing inside container#

If command like pi, codex, gemini, opencode, or claude is missing/old.

Fix#

bash
ags update-agents

pnpm reports ERR_PNPM_UNEXPECTED_STORE, MODULE_NOT_FOUND under /usr/local/pnpm, or Pi loads from .npm-global#

Cause:

  • a pnpm self-update or install script wrote pnpm's own shims into the persistent agent runtime volume
  • old npm-global agent installs can shadow the pnpm-managed AGS agent shims
  • those shims can disagree with the store used by the globally installed agent CLIs

Fix#

bash
ags update-image
ags update-agents

AGS keeps agent CLIs in /usr/local/pnpm, but runtime pnpm should come from the sandbox image (/usr/local/bin/pnpm) so stale persistent shims do not shadow it. update-agents also removes old npm-global pi/codex/gemini/opencode shims from the sandbox cache.

SSH problems (git auth/signing)#

Symptoms:

  • cannot push
  • signing fails
  • keys not loaded

Fix#

  1. Re-run setup:
    bash
    ags setup
  2. Confirm public keys are added in GitHub:
    • auth key as SSH key
    • signing key as SSH signing key
  3. Re-run:
    bash
    ags doctor

If keys are passphrase protected, ssh-add may prompt interactively.

Secret not available inside container#

Symptoms:

  • tool auth failures
  • missing token env vars

Check#

  • Is [[secret]] / [[tool.secret]] configured correctly?
  • Is source env var actually set and non-empty?
  • If using secret_store, does secret-tool lookup ... return a value?
  • If using command, is the executable present and executable on the host?
  • Does the helper finish within five seconds, exit 0, and print exactly one non-empty UTF-8 value (optionally followed by one \n or \r\n)?
  • Is the command declared in the user/global config? Repo-local .ags/config.toml command sources are rejected.
  • Run ags doctor; it checks command availability and lookup success without printing the resolved value or helper stderr/stdout.

Fix#

  • Re-run ags setup to re-enter secrets (if using interactive keyring flow)
  • Export env vars before launching ags
  • Run the configured helper directly on the host to diagnose native credential-store access. Avoid sharing its output in logs or bug reports.

Command helpers receive only PATH, HOME, USER, LOGNAME, DBUS_SESSION_BUS_ADDRESS, and XDG_RUNTIME_DIR when those variables exist. If a helper depends on other ambient host variables, wrap it in a narrowly scoped adapter that establishes only the required context. Resolved values are delivered as ordinary container environment variables and can be inspected by sandboxed processes.

Browser mode fails#

Symptoms:

  • --browser exits early
  • debug endpoint not reachable

Check#

  • [browser].enabled = true
  • [browser].command exists and executable
  • [browser].profile_dir is valid
  • [browser].debug_port is non-zero and free

Fix#

bash
ags doctor
ags --agent pi --browser

If needed, try a different debug port.

Auth proxy: URL opens are auto-denied#

Symptoms:

  • Agent tries to open a URL (e.g. OAuth login) but nothing happens
  • Shim logs show prompt denied

Cause:

  • No AGS dialog renderer is available, so the proxy cannot show the allow/deny dialog and defaults to deny.

Fix#

Enable the branded Glimpse-backed host UI dialog via [host_ui], or install a fallback dialog tool:

bash
# Debian/Ubuntu (GNOME)
sudo apt install zenity

# Fedora (GNOME)
sudo dnf install zenity

# KDE
sudo apt install kdialog   # or: sudo dnf install kdialog

Auth proxy: socket connection failures#

Symptoms:

  • Shim prints failed to connect to auth proxy socket or times out
  • OAuth flows hang

Cause:

  • The per-run runtime directory or socket was not created (e.g. $XDG_RUNTIME_DIR is missing or not writable).

Fix#

Verify your runtime dir:

bash
echo "$XDG_RUNTIME_DIR"
ls -la "$XDG_RUNTIME_DIR"

If unset/missing, set it before running ags:

bash
export XDG_RUNTIME_DIR="/run/user/$(id -u)"

MCP server re-authenticates every session#

Symptoms:

  • MCP servers (e.g. Linear) ask to re-authenticate on every ags run
  • OAuth tokens are not persisted

Cause:

  • MCP auth tokens are stored in ~/.mcp-auth inside the container, which is ephemeral by default.

Fix#

Mount the token directory from your host:

toml
[[mount]]
host = "$HOME/.mcp-auth"
container = "/home/dev/.mcp-auth"
mode = "rw"
kind = "dir"
create = true

To also skip the allow/deny dialog for known providers:

toml
[auth_proxy]
auto_allow_domains = ["mcp.linear.app"]

Auth proxy: OAuth callback not received#

Symptoms:

  • Browser opens the OAuth provider page and redirects to localhost:<port>/callback
  • But the agent inside the container never receives the auth code

Cause:

  • The callback port was already in use on the host when the proxy tried to bind it.
  • Or the OAuth provider uses a non-standard callback parameter name that the shim does not detect.

Fix#

  • Retry the flow — the proxy binds the callback port dynamically per session.
  • If persistent, check for port conflicts: ss -tlnp | grep <port>.
  • The shim detects redirect_uri, callback_url, return_url, and redirect_url query parameters. Other parameter names are not recognized and will fall back to a simple (non-callback) URL open.

Config parse/validation errors#

Symptoms:

  • startup fails with validation message

Fix#

  • Compare your file with config/config.example.toml
  • Verify enums are valid:
    • mount mode: ro|rw
    • mount kind: dir|file
    • mount when: always|browser
  • Verify required strings are non-empty

ags command not found#

If installed from source but not in PATH.

Fix options#

Run via cargo:

bash
cargo run -p ags -- --agent pi

Or self-link:

bash
cargo run -p ags -- install --link-self

Ensure ~/.local/bin is in PATH.

Alias/wrapper commands not found#

If you ran ags create-aliases but short names are missing.

Check#

  • Wrappers mode writes to ~/.local/bin
  • Aliases mode updates shell rc and requires shell reload

Fix#

bash
ags create-aliases --mode both
exec $SHELL

Podman runtime issues#

Symptoms:

  • podman command failures
  • permission/network oddities

Check#

  • Podman installed and working rootless
  • user session has required Podman setup

Run a quick check:

bash
podman info

Then rerun:

bash
ags doctor