Agent
Command to run coding agents in a sandbox and manage the Docker sandbox backend
The agent command runs coding agents through the Stashbase Agent Proxy, either in the native OS sandbox or in an isolated Docker sandbox.
stashbase agent <COMMAND> [OPTIONS]This page is the command reference. For how agents get secrets, see how it works. For profiles, sessions, MCP, and logs, see the Agents guide.
Run
Run an agent with a profile. Pass the agent's command after --.
stashbase agent run --profile <PROFILE> [OPTIONS] -- <COMMAND>Config environment options
Set profile [config_env] variables for a single run.
Prop
Type
stashbase agent run --profile coding --config-env NODE_ENV=test --config-env PORT=4000 -- claudeDocker sandbox options
These options override the profile's [sandbox] settings for a single run.
Prop
Type
stashbase agent run --profile coding --docker-sandbox true -- claude
stashbase agent run --profile coding --docker-image node:22-alpine --docker-memory 2g -- codexRemote options
Run through a remote Agent Proxy session. See Remote sessions.
Prop
Type
stashbase agent run --remote --profile coding -- codex
stashbase agent run --remote --remote-mode full --profile coding -- codexSSH options
Start the agent on a machine prepared with stashbase ssh.
Prop
Type
stashbase agent run --ssh mybox --remote-dir /srv/my-repo --profile coding -- codexWorktree options
Run the agent in its own git worktree. See Git worktrees.
Prop
Type
stashbase agent run --profile coding --worktree -- claude
stashbase agent run --profile coding --resume amber-river-storm -- claudeWorktrees
Review and clean up agent worktrees. Everything is local; nothing is pushed.
stashbase agent worktrees <COMMAND>| Command | Description |
|---|---|
list | Show each worktree's status and commits not merged yet. |
merge <NAME> | Merge a run's branch. Options: --squash, -m <MESSAGE>, --keep. |
clean | Remove merged agent work. --all removes everything. |
remove <NAME> (alias delete) | Discard one run. --keep-branch keeps its branch. remove --all discards all runs; --yes skips the prompt. |
Docker
Manage Docker sandbox backend resources.
stashbase agent docker <COMMAND> [OPTIONS]Doctor
Check whether the Docker sandbox backend can run on this machine: the docker CLI, the daemon, and the default image, with its age and the Claude Code and Codex versions inside it. Exits non-zero if anything isn't ready, and says how to fix a failed check, such as installing Docker, starting the daemon, or adding your user to the docker group.
stashbase agent docker doctor [--json]Build
Build or rebuild the default Docker sandbox image from the default Dockerfile.
stashbase agent docker build [OPTIONS]Prop
Type
Status
List Docker sandbox networks and containers on this machine, with session ID, creation time, and whether each belongs to a live local session.
stashbase agent docker status [--json]Cleanup
Find and remove networks and containers left behind by a run that didn't tear down cleanly, for example after stashbase was killed with SIGKILL. Resources that belong to live local sessions are skipped.
stashbase agent docker cleanup [OPTIONS]Prop
Type