droneship run
Run an agent in a sandbox: work with it live, or hand it a task.
Live, it reattaches to your sandbox if one is running. With -p it works on the task alone and the sandbox stops when it’s done; list -a shows how it went, and resume picks up its conversation.
Arguments are passed through to the agent; put -- first for any that droneship would otherwise read as its own.
--new launches another sandbox instead of reattaching. --fresh discards this repo’s saved workspace before launching (it has no effect on a sandbox that is already running; kill it first).
droneship run [OPTIONS] AGENT [ARGS]Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
AGENT |
Which agent to run: claude, codex |
ARGS |
Arguments passed through to the agent (optional) |
Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--id ID |
Which sandbox (your only one when omitted) | |
--backend BACKEND |
Which backend provisions it (the deployment default is right for most users; ask your admin for others) | |
--timeout DURATION |
Hard cap: teardown at this age even if in use (e.g. 8h, 90m; plain seconds work) | 8h |
--idle DURATION |
Teardown after this long with nobody connected (default 30m; 0 disables) | |
--policy-bundle [baseline-secure|pci-scope|open-dev] |
Egress policy, resolved server-side | baseline-secure |
--isolation [NONE|OS|KERNEL|HARDWARE] |
Minimum isolation the sandbox must provide (refused if unavailable) | |
--region [auto|us|eu|ap] |
Where the sandbox runs (Modal). auto picks us/eu/ap from your timezone. Pinning a region costs more (Modal: 1.15x), and model calls still go through the gateway, so a far region can make the agent slower | |
--byok NAME |
Provider key to send, named by env var (repeatable). Read from your environment, never the command line. Remembered for this profile | |
--direct |
Skip the AI Gateway and call the provider directly (needs –byok or –subscription; loses gateway policy, scanning and the KERNEL isolation floor) | |
--no-byok |
Send no provider key, and forget any this profile remembers | |
--subscription, --sub |
Bill your own plan (Claude Pro/Max, ChatGPT): sign in inside the sandbox | |
--repo REPO |
Repo to clone: owner/name, a GitHub URL, or a git@ URL (this checkout’s origin when omitted) | |
--ref REF |
Branch, tag or commit to check out (your current branch when omitted) | |
--no-repo |
Start an empty sandbox, ignoring the current checkout | |
--trust-repo-mcp |
Start the MCP servers in the repo’s .mcp.json (they run the repo author’s code; off by default) | |
--fresh |
Discard the saved workspace for this repo and start clean (destructive) | |
--ephemeral |
Save nothing — no workspace is kept after teardown | |
--yes |
Answer yes to every confirmation (required when not on a terminal) | |
--connect [web|terminal] |
How you reach the sandbox (terminal, unless the agent only has a web UI) | |
--new |
Launch another sandbox instead of reattaching to one already running | |
--detach, -d |
Don’t wait: with -p, print the task’s id and return; without, start the sandbox and print how to reach it | |
--prompt, -p TEXT |
Give the agent a task to work on alone; the sandbox stops when it finishes (follow it with list -a, logs, resume) | |
--notify-url URL |
With -p: POST a signed notice to this https URL when the task ends (verify it with the key from droneship webhook key) |
|
--notify-context JSON |
With –notify-url: a JSON object echoed back in the notice | |
--model MODEL |
The model the agent uses: an alias such as sonnet or opus, or a full model id | |
--ask |
Have Claude ask before each command (by default it doesn’t: the sandbox is the boundary) | |
--forward, -L SPEC |
Forward a sandbox port to your machine: PORT or LPORT:HOST:RPORT (repeatable) |
Examples
Section titled “Examples”Start an interactive Claude Code session on the current repo. If a sandbox for it is already running, the command reattaches to it:
droneship run claudeStart a prompt run in the background (-p with -d). Check on it later with droneship list -a and droneship logs:
droneship run claude -p "fix the flaky test in tests/api" -dRun the same task on a different model:
droneship run claude -p "fix the flaky test in tests/api" -d --model sonnetRun Codex on a specific repo and branch:
droneship run codex --repo github.com/me/app --ref mainStart a second sandbox instead of reattaching. --ephemeral makes it a scratch sandbox that saves nothing; this one uses the pci-scope egress bundle and stops after 2 hours:
droneship run claude --new --ephemeral --policy-bundle pci-scope --timeout 2hStart the MCP servers in the repo’s .mcp.json. They are off by default, because they run the repo author’s code (Tools and MCP):
droneship run claude --trust-repo-mcpForward port 3000 in the sandbox to your machine:
droneship run claude -L 3000Generated from the CLI. Verified against droneship 1.12.0.