Workspaces

This page covers what a workspace keeps and how long it lasts, how to list and delete workspaces, and how to run a sandbox without one.

A workspace is the saved copy of a sandbox’s files, one per repo. When a sandbox stops, the next droneship run claude on that repo resumes on it, with your files and Claude’s past conversations in place.

1. List your workspaces.

   droneship workspace list

   The table shows each workspace (its repo), its Source, when it was Last used, and whether a sandbox is In use on it. Under it:

   Delete one with droneship workspace delete <workspace>, or this directory's or repo's with droneship workspace delete

   -v adds each workspace’s full Name. --json prints a JSON array for scripts.

2. Delete one you no longer need.

   cd ~/src/my-repo
   droneship workspace delete

   With no name, it deletes the workspace for the repo you’re in. To name one, give its repo as the list shows it, or its Name from list -v (or a unique start of it, eight characters or more). The CLI shows what it will delete and asks first:

   This permanently deletes 1 saved workspace(s): their files, any work you did not pull or commit, and their conversations. It cannot be undone.
   Are you sure? [y/N]:

   --yes skips the question, and is required when there is no terminal. --all deletes every workspace you have.

Caution

Deleting a workspace removes any work in it that you haven’t pulled or pushed. Copy it to your machine first with droneship pull.

What a workspace keeps

• Your repo’s files, including uncommitted work and commits you haven’t pushed.
• A short list from the sandbox’s home directory: Claude’s conversations and todos, its settings.json and commands/, shell history, ~/.local, and package caches (pip, uv, npm, yarn, Go and Cargo, emptied above 2 GB).
• No credentials. SSH keys, Claude’s sign-in, and your git config are not saved in it.

Anything an agent installs into ~/.local/bin, and any hook in the saved settings.json, runs again in every later session on that workspace. This is how a uv tool install carries over between sessions. To start from a clean clone without them, use --fresh.

How long a workspace lasts

A workspace lasts until you remove it. droneship kill stops the sandbox and keeps the workspace. Two things remove it:

droneship workspace delete        # delete it now
droneship run claude --fresh      # discard it, then launch on a clean clone

--fresh has no effect on a sandbox that’s already running, so kill that first.

Skip the workspace

To run a sandbox that saves nothing when it goes:

droneship run claude --new --ephemeral

--ephemeral also lets you run a second live sandbox on the same repo while your first one holds the workspace. Run several agents in parallel shows how.

Prompt runs (-p) don’t use your workspace. Each one starts from a fresh clone and keeps its own snapshot for 7 days (Background runs and logs).

A workspace that a sandbox is using can’t be deleted. workspace delete skips it and says so:

  skipped <workspace>: a sandbox is using it

More: Workspace, droneship workspace, Pick up where it left off.

Next

• Review and land: get the agent’s work out before you delete.
• Pick up where it left off: resume a past conversation.
• Console: see your sandboxes in the browser.