Skip to content

Background runs and logs

This page is a reference for prompt runs: the -p and -d flags, reading the log, exit codes, listing runs, and how long stopped runs are kept. For the whole flow, from handing off a task to answering it, see Hand off a task.

  1. Start a prompt run and get your terminal back.

    Terminal window
    droneship run claude -p "fix the flaky test in tests/test_api.py" -d
    <id>  started: Claude Code on https://github.com/you/my-repo @ main
      droneship logs -f <id>

  2. Follow its log.

    Terminal window
    droneship logs -f <id>

  3. See how your runs went.

    Terminal window
    droneship list -a

Start a run: -p and -d

Section titled “Start a run: -p and -d”

-p "<task>" starts a prompt run: Claude works on the task with no interactive session attached. Every prompt run starts its own sandbox with a fresh clone of your repo at your current branch, so it doesn’t reattach to an existing sandbox or use your saved workspace. It refuses --id. The sandbox stops when the agent finishes.

You run What happens
run claude -p "…" -d Prints the run’s id and returns once the sandbox starts.
run claude -p "…" Prints the id, then streams the log and exits with the agent’s exit code.

Without -d, Ctrl-C stops watching, not the run:

Detached; it keeps running. droneship logs -f <id>

Prompt runs are Claude Code only. They use your exported ANTHROPIC_API_KEY, your Claude plan through a claude setup-token token exported as CLAUDE_CODE_OAUTH_TOKEN (or --byok), or the API key you saved on the console’s Settings page under Model keys, and refuse --subscription, --direct and --ask (Harnesses and models has the details). Choose the model with --model, for example --model sonnet. Without it, a prompt run uses the default model. 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).

Read the log

Section titled “Read the log”
Terminal window
droneship logs <id>       # what's there now
droneship logs -f <id>    # keep streaming while the agent runs
droneship logs --raw <id> # the agent's JSONL log, unchanged

The log is one row per action, with the time it happened, then a count:

08:34:32  start   claude-opus-5-5
08:34:37  cmd     git commit --allow-empty -m 'test one'  ok
08:34:39          <Claude's message>
08:34:39  end     2 turns · 7s                            done
1 actions

A row names what the agent did (read, search, cmd, web, write, subagent or tool), its target, and the outcome: ok, denied or error. When a command succeeds and its output reports a test count, the outcome is <n> passed or <n> failed instead. A write row shows the lines it added and removed instead. Rows with no verb are Claude’s messages. A failed run’s end row gives the reason and reads failed, and the count adds · <n> failed or denied when any action did. --raw prints every event as the agent wrote it, for jq or your own tooling. On a run that has already stopped, logs -f replays the saved log and exits with the run’s exit code.

logs reads prompt runs only. On an interactive sandbox it says so:

<id> is an interactive sandbox; `logs` shows prompt runs (`droneship run claude -p …`). Open it with droneship shell --id <id>.

Use the exit code

Section titled “Use the exit code”
Command Exits with
run claude -p "…" (no -d) The agent’s exit code
logs -f <id> The agent’s exit code, once it finishes
logs <id> 0 whenever the log was read

If logs -f can’t learn the result, it exits 1 and says why, either that the stream closed before the agent finished or that the result is unknown. A script can use this to wait for a run and act on the result:

Terminal window
id=forge-1a2b3c4d
if droneship logs -f "$id" > run.log; then
  echo "task passed"
fi

List runs

Section titled “List runs”
Terminal window
droneship list -a
droneship list -a --json

list shows running sandboxes. -a adds stopped prompt runs you can resume, and interactive sandboxes that ended in the last day (Activity explains those). A run’s status reads running, done, done · PR #<n>, blocked or failed (exit <code>), with how long ago it finished, and no snapshot when it can no longer be resumed. --json prints one object per sandbox for scripts, and -v shows every column on a narrow terminal.

How long stopped runs are kept

Section titled “How long stopped runs are kept”

A stopped run stays in droneship list -a, with its log and snapshot, for 7 days. After that, logs can’t find it:

No prompt run named <id>. droneship list -a shows the ones you can read (stopped runs are kept 7 days).

To remove one sooner:

Terminal window
droneship kill <id>
Deleted stopped run <id> and its snapshot (local SSH key discarded)
  removed from droneship list -a; its snapshot is deleted (or, if that fails, expires within 7 days)

On a run that is still going, kill stops it and keeps its snapshot, so you can still droneship resume claude <id>.

More: Prompt run, droneship logs, droneship list, droneship kill, Activity.

Next

Section titled “Next”