Skip to content

What is Droneship

Droneship runs coding agents (Claude Code, Codex, or an agent you wrote) in isolated cloud sandboxes. You start one from your repo with the droneship CLI, work with it live or give it a task, and get its changes back as a git branch. This section introduces the product, walks through a first run, and defines the terms the rest of the docs use.

Terminal window
cd ~/src/my-repo
droneship run claude

This starts Claude Code in a cloud sandbox with a fresh clone of your repo at your current branch, and attaches your terminal to its session. Running the command again reattaches to the same sandbox. To start another one alongside it, add --new --ephemeral, or give it a task with -p.

You can use it in two ways: pair with the agent in a live session, or hand it a task and check the result later.

Why Droneship

Section titled “Why Droneship”

A coding agent acts on whatever it can reach: your files, the credentials in your shell, the network. An instruction in its prompt doesn’t change what it can reach, so the limits have to be enforced outside the agent’s process. Droneship moves the agent off your laptop into a cloud sandbox and enforces those limits around it, so you can give it real work on a real repo.

  • It runs on a machine that isn’t yours. Each run gets its own sandbox with a fresh clone of the repo. What the agent writes and runs stays there until you review it with droneship diff and bring it back with droneship pull or droneship pr.
  • It uses your credentials without holding them. With Claude Code, model keys and the GitHub token are held by a sidecar outside the sandbox and added to requests on the way out.
  • It reaches only what the policy allows. Egress is limited to the hosts in the sandbox’s egress policy, enforced outside the sandbox. MCP servers must be on that list too.
  • It starts ready to work. The sandbox boots from a pinned image with Node.js 20, Python 3 (with pip and venv), git, gh, make and a C toolchain, so the agent’s first commands are about your task rather than installing tools.
  • You can see what it did. droneship logs shows a prompt run’s activity while it runs and after it finishes.
  • It’s cheap to leave running and to run several. A sandbox stops after 30 minutes idle (8 hours at most) and saves its workspace for next time, and you can start more than one on the same repo, each in its own sandbox.

The research behind enforcing limits outside the agent, cited on droneship.run: Anthropic’s assessment of models acting beyond their intended scope, Pillar Security on agents crossing sandbox boundaries through files that trusted tools later run, and METR’s investigation of isolated agents coordinating through a shared package repository.

What it does

Section titled “What it does”
  • Starts a sandbox from one command. droneship run claude (or codex) provisions the sandbox, clones the repo and starts the agent.
  • Needs only the CLI on your laptop. You don’t need Docker, a cloud account or cloud credentials. You sign in once with droneship login.
  • Returns work as a branch. The agent works on a clone of your repo. droneship pull fetches its work into a local branch, and droneship pr opens a pull request for it.
  • Saves a workspace per repo. The sandbox’s files are saved when it stops, and the next droneship run claude on that repo resumes from them.
  • Runs Claude without per-command prompts. Claude doesn’t ask before each command, because the sandbox is the boundary. Pass --ask to turn the prompts back on.

Security defaults

Section titled “Security defaults”

These controls are on without passing a flag. Each one describes what it lets you do with the agent.

  • Egress allowlist: the sandbox can reach only the hosts in its egress policy, so you can leave a run unattended.
  • Isolation and identity: each sandbox is isolated from the others and from your laptop, so you can run several at once.
  • Credentials stay outside the box: when Claude Code runs through the Highflame gateway, a separate sidecar adds model keys and the GitHub token to outbound requests, so the agent can use them without holding them.
  • Tools and MCP: start the MCP servers in the repo’s own .mcp.json with --trust-repo-mcp, and keep keys out of the file.
  • Activity: droneship logs shows what a prompt run’s agent did, while it runs or after it finishes.
  • Auto-stop: an idle sandbox shuts itself down, so one you forgot about doesn’t keep running.

The security overview explains how these fit together.

Compared with running the agent locally

Section titled “Compared with running the agent locally”
Agent on your laptop Agent in Droneship
Isolation Runs with your files, shell history and credentials Runs in its own sandbox with a fresh clone of the repo
Parallel runs One checkout, so one agent at a time per repo --new --ephemeral or -p starts another sandbox on the same repo
After you disconnect Stops when your laptop sleeps or the connection drops Keeps working in the sandbox for up to --idle (30m by default) after you disconnect; for longer, raise --idle or hand it off with -p. See Auto-stop
Credentials The agent can read whatever your user can No cloud credentials needed; with Claude Code, by default, model keys stay in a sidecar

In this section

Section titled “In this section”
  • Quickstart: install the CLI, sign in and run your first sandbox.
  • Core concepts: sandboxes, harnesses, workspaces and prompt runs.

After that, Pair with an agent covers the everyday live workflow.