Launch modes¶
terok-executor supports four ways to run an agent, plus a separate tool runner for sidecars.
Headless¶
terok-executor run claude . -p "Fix the failing test"
terok-executor run claude . -p "Refactor auth" --model sonnet --max-turns 10
Fire-and-forget. The agent runs autonomously and streams output to the
terminal. Exits when the agent finishes, hits --max-turns, or reaches
--timeout (default 1800 s).
Interactive¶
Opens a shell session inside the container. The agent CLI is installed and ready; credentials and the repository are pre-configured. Use this to drive the agent manually.
Web¶
Launches toad, a multi-agent TUI served over HTTP. Access it in a browser at the printed URL.
Tool mode¶
Runs a sidecar tool in its own container. Arguments after -- are
passed to the tool binary. See Agents for
the list of supported tools.
Managing containers¶
terok-executor list # list running containers
terok-executor stop my-task # stop a specific container
Common flags¶
| Flag | Description |
|---|---|
--gate / --no-gate |
Route git clone through the host-side gate mirror, or skip it and let the container clone upstream directly (default: on — the gate is faster and offers staleness comparison; the shield firewall is unaffected) |
--restricted |
No auto-approve, no-new-privileges |
--branch <ref> |
Check out a specific git branch |
--name <name> |
Container name override |
--gpu |
Enable GPU passthrough |
--git-identity-from-host |
Use the host's git user.name and user.email |
--shared-dir / --shared-mount |
Mount a host directory into the container |
--timeout <seconds> |
Override the default timeout |
--model <name> |
Model override (headless mode) |
--max-turns <n> |
Limit agent turns (headless mode) |