Agent Sandbox manual
Build freely.
Know the boundary.
Everything you need to install, operate, configure, troubleshoot, and extend Agent Sandbox—generated directly from the repository documentation.
Choose a path
Start with the work in front of you.
01
New to AGS
Open the overview →
02
Get running
Requirements, installation, first-time setup, and your first agent launch.
Daily operation
Configure AGS →
03
Shape the environment
Mounts, secrets, repo overlays, browser access, and clipboard controls.
Going deeper
Explore architecture →
Understand the system
Launch plans, host bridges, socket protocols, relays, and security boundaries.
Common tasks
Go straight to the answer.
Set up AGSKeys, config, image, and verification
→
Launch an agentModes, passthrough flags, and runtime flow
→
Configure mountsRead-only, read-write, optional, and per-repo
→
Harden a foreign repoWhat lockdown keeps and what it cuts
→
Fix clipboard pasteApproval windows, shims, and diagnostics
→
Run TestcontainersPolicy-gated access through PSP
→
The complete library
14 source documents. One coherent manual.
405 searchable sectionsUnreleased latest release
Start here
Operate
CommandsUnderstand every command, run flag, side effect, and runtime service Agent Sandbox can activate.→ConfigurationConfigure mounts, secrets, browser integration, clipboard access, host UI, and update behavior.→Startup hooksPrepare launches with trusted host executables, a versioned JSON protocol, and validated environment, file, and mount contributions.→1Password Secure NotesInject a CLI-selected 1Password Secure Note into only the final agent process tree.→TroubleshootingDiagnose common image, mount, terminal, SSH, browser, clipboard, and host-service problems.→
Integrate
Understand
ArchitectureFollow the pipeline from CLI parsing and validated configuration to a rootless Podman launch plan.→Host UI bridgeThe protocol, lifecycle, security boundaries, and ownership model behind sandbox-safe host windows.RFCApp origin relayHow host-owned webviews reach temporary HTTP applications running on sandbox-local ports.→Config editor researchDesign research for comment-preserving TOML editing, layered configuration, backups, and TUI structure.Research