Skip to content

Isolation and identity

You can run several agents in parallel because each one gets its own sandbox, its own clone, its own kernel boundary and its own identity. One sandbox’s files and credentials are not present in another. Your laptop holds only your Droneship sign-in.

Terminal window
droneship run claude -p "fix the flaky test in tests/test_api.py" -d
droneship run claude -p "add type hints to src/billing/" -d
droneship run claude --new --ephemeral

The launch prints the isolation level it got:

  isolation: KERNEL

Isolation

Section titled “Isolation”

Sandboxes run under gVisor, which gives each one its own kernel in user space, between the agent and the host. Droneship names four levels, and a launch states the lowest one it will accept:

Level Means
NONE No isolation layer
OS Operating-system isolation, sharing the host kernel
KERNEL Its own kernel (gVisor)
HARDWARE A microVM. The hosted service refuses it

You don’t need to set it. A launch whose key stays in the credential sidecar, and every task, requires at least KERNEL. The level drops to OS when a long-lived credential has to live inside the sandbox:

  • With --subscription, you sign in to your plan inside the sandbox, so that launch is held at OS and can’t run at --isolation KERNEL.

  • When a GitHub token for a private repo is in the sandbox’s environment, the launch says so:

      a GitHub token is in this sandbox to reach a private repo — isolation is OS, not KERNEL

    With Claude Code the token is held by the sidecar by default, so a private repo gets KERNEL like a public one.

--direct skips the gateway and with it the KERNEL floor. To require a level, pass --isolation. The level is a minimum: a launch that can’t meet it is refused rather than run at a lower level.

Terminal window
droneship run claude --isolation KERNEL

Credentials stay outside the sandbox

Section titled “Credentials stay outside the sandbox”

With Claude Code or Codex on the gateway, the sandbox doesn’t hold the gateway credential or a --byok key you send. A sidecar container next to it, named creds, holds them and adds them to requests on the way out:

  • Model calls. The agent talks to the sidecar, and the sidecar adds the gateway credential. A --byok key you send stays in the sidecar too.
  • Git. For a repo that needs a GitHub token, the sidecar adds it to git traffic for that one repo only, and opens pull requests for a task.

The sandbox’s environment holds placeholders. Every task uses the sidecar. With --subscription, the sidecar holds the gateway credential, and your plan’s sign-in is stored in the sandbox. --direct launches keep their credentials in the sandbox’s environment.

Per-sandbox identity

Section titled “Per-sandbox identity”

Each sandbox gets its own identity when it starts, registered on your behalf, in your account:

  • Its own. Each sandbox gets a distinct identity, so each is attributable on its own and can be revoked on its own.
  • Scoped. It carries a fixed set of scopes. Tokens issued from it get the intersection of what they ask for and those scopes.
  • Short-lived. It expires with the sandbox’s hard cap, and it’s revoked when the sandbox stops, is killed, or fails to launch.

A second, separate credential lets the sandbox call the gateway for models and tools. It’s revoked with the identity.

In the console, open the sandbox and choose the Identity tab. Workload identity shows its URI (wimse_uri), its scopes, and when it expires (expires_at). The identity’s id tags the sandbox’s events and its model calls, which is how Activity ties them together.

No cloud credentials on your laptop

Section titled “No cloud credentials on your laptop”

droneship login stores a sign-in for one account and project. The CLI needs no other credential. Sandboxes are provisioned by the hosted Droneship service, so you don’t install a cloud SDK or hold a cloud provider key to run one.

More: Core concepts, Harnesses and models, Login and profiles.

Next

Section titled “Next”