Core concepts

This page defines the terms the rest of the docs use: sandbox, harness, workspace, prompt run, organization and project, and auto-stop. Each section ends with links to the pages that cover it in detail.

Sandbox

A sandbox is an isolated cloud machine running one agent on one repo. droneship run claude creates one, or reattaches to the sandbox you already have for this repo. --new --ephemeral (or a -p prompt run) starts another alongside it, and --id picks a specific one.

droneship list          # your running sandboxes, with repo@branch
droneship kill <id>     # shut one down

The sandbox gets a fresh clone of your repo’s origin at your current branch. Its work comes back through git: droneship diff, droneship pull and droneship pr, run from your checkout.

More: droneship run, Isolation and identity, Review and land.

Harness

The harness is the agent the sandbox runs. You name it after run:

Command	Runs
droneship run claude	Claude Code
droneship run codex	OpenAI Codex CLI

The registry ids, such as claude-code, are also accepted.

More: Harnesses and models, Harness reference.

Workspace

A workspace is the saved copy of a sandbox’s files, one per repo. It persists after the sandbox stops, and the next droneship run claude on that repo starts from it. If the saved tree is clean it switches to your current branch. If it has uncommitted work, it stays on the branch it was left on, and the CLI says which.

Besides the code, a workspace keeps a short list of things from the sandbox’s home directory: Claude’s conversations, todos, settings.json and commands/, shell history, ~/.local, and package caches (pip, uv, npm, yarn, Go, Cargo). It doesn’t keep credentials.

droneship workspace list          # your saved workspaces
droneship workspace delete        # permanently delete this repo's workspace
droneship run claude --fresh      # discard it and start clean
droneship run claude --ephemeral  # save nothing when this sandbox goes

droneship kill keeps the workspace. Only droneship workspace delete or --fresh removes it.

More: Workspaces, droneship workspace.

Prompt run

A prompt run gives the agent a task (-p) and runs it without an attached session. The sandbox stops when the agent finishes.

droneship run claude -p "fix the flaky test in tests/test_api.py" -d
droneship list -a          # running and stopped runs
droneship logs -f <id>     # what the agent is doing
droneship resume claude <id>

Each prompt run gets a fresh clone of the repo at your current branch and doesn’t use your saved workspace, so it can run while you work in your own sandbox on the same repo. Without -d the CLI streams the output and exits with the agent’s exit code. A stopped run stays in droneship list -a for 7 days. To keep its changes, resume it and push. Prompt runs start the MCP servers in the repo’s own .mcp.json only with --trust-repo-mcp, so pass it only on repos you trust (Tools and MCP).

More: Hand off a task, Background runs and logs.

Organization and project

Your sign-in is tied to one account and one project, and your sandboxes belong to that project. droneship whoami shows which ones you’re on. To switch project, sign in again:

droneship login --project payments-api

In the console, the organization holds its members, usage and billing. Each project has its own Sandboxes page, which shows the sandboxes you launched.

More: Login and profiles, The console, Work as a team.

Auto-stop and resume

A sandbox shuts itself down under two limits:

• Idle: with nobody connected for 30 minutes, it shuts down. Set it with --idle (0 turns it off).
• Hard cap: after 8 hours it shuts down even if you’re connected. Set it with --timeout.

When an interactive sandbox stops, its workspace is saved, so droneship run claude picks up the files, and droneship resume claude lets you choose from your past Claude conversations. A stopped prompt run restores from its snapshot with droneship resume claude <id>.

A dropped connection doesn’t stop the sandbox. Claude runs in tmux inside the sandbox, and droneship run claude reattaches.

More: Auto-stop, Resume your work, droneship resume.