Docs
Sign in

CLI

Claude sessions

A session is your project in a sandbox with Claude running in it. It lives until you remove it: detach, close the laptop, come back tomorrow.

What gets uploaded

spawn claude uploads the project you’re in: the top of the git repository, or the current folder outside git. It refuses your home directory and /.

  • In a git repository it sends what git would: tracked files plus untracked ones that .gitignore doesn’t exclude, so uncommitted work comes along. The .git folder goes too, so Claude sees your history and branches.
  • Outside git it sends the folder, skipping node_modules, .venv and __pycache__.
  • Secrets stay behind: .env and .env.*, private keys (*.pem, *.key, id_rsa* and similar), .netrc, .pgpass, keystores and credentials.json. Example files like .env.example are kept. A secret that is committed to git still travels inside .git; spawn warns when that happens.
  • Credentials in git remote URLs are removed. Symlinks pointing outside the project are skipped.
  • The compressed upload can be up to 500 MiB. Over that, spawn lists the largest files.

The first upload from a folder asks you to trust it, after showing exactly this summary. Trust is remembered on your machine (nothing is written into the project); spawn trust --forget makes it ask again. Leave more out, or put a skipped file back, with the upload settings in the reference.

How Claude gets your key

Claude runs on the Anthropic key you saved on the Secrets page, but the key never enters the sandbox. The sandbox gets a short-lived token that works only from inside it, and spawn’s model proxy adds your key on the way to Anthropic. Anything that runs in the sandbox can use Claude while the session is up; nothing in it can read or copy your key.

Resume or start new

spawn remembers the sessions started from each folder. Run spawn claude where a session exists and it asks: resume it, start a new one, or pull its changes first.

  • --new always starts a new session.
  • --yes skips the questions: it resumes, and trusts the folder.
  • --name names the session (the folder name by default).
  • Anything after -- goes to Claude: spawn claude -- --model sonnet. It applies when Claude starts, not to a Claude that’s already running.

Sandbox size

2cpu-4gb 2 vCPU · 4 GB
Small projects and quick fixes.
2cpu-8gb 2 vCPU · 8 GB
The default. What Claude Code needs in practice.
4cpu-16gb 4 vCPU · 16 GB
Bigger builds and test suites.
8cpu-32gb 8 vCPU · 32 GB
Heavy builds, many services at once.

Pick one with spawn claude --size 4cpu-16gb, or set a default with the size setting. Size applies to new sessions.

Detach, disconnect, come back

Claude runs in a persistent terminal inside the sandbox, so it keeps working when your terminal goes away.

  • Detach with Ctrl+\: Claude keeps working and the sandbox stays up. Change the key with the detachKey setting. Ctrl+C goes to Claude as usual.
  • Reattach with spawn attach. If Claude has exited, it continues the last conversation.
  • If the connection drops, spawn reconnects on its own, up to five times. A dropped connection never pauses the sandbox.
  • A shell in the same sandbox: spawn shell. Exiting it doesn’t pause anything.
  • Your own browser: spawn open opens the session page, spawn open --code the editor, and spawn open --preview 3000 a server the agent started on port 3000.

Typing over a slow connection feels instant: spawn echoes your keystrokes locally when the round trip is slow, and corrects them when the sandbox answers. Turn it off with predictiveEcho.

Pausing

A sandbox pauses itself after 15 minutes idle, counted only while no terminal is attached and Claude isn’t working. When Claude exits, spawn pauses the sandbox right away. A paused sandbox resumes in a few seconds when you attach, open a shell, pull or open a preview.

  • spawn stop pauses a session now.
  • spawn claude --idle-timeout 1h sets a new session’s idle time (60 seconds to 24 hours; also the idleTimeout setting).
  • spawn rm ends the session and deletes its sandbox. Changes you haven’t pulled are lost, so it asks first.

Bring the changes back

Terminal 
spawn pull --dry-run   # see what would change
spawn pull             # apply it

spawn pull applies everything Claude changed since the upload, committed or not, to your folder as uncommitted edits. Review them like any change, then commit.

It only touches files that still match what was uploaded. If you’ve edited one of them since, it stops and lists the files: commit or stash your work and pull again, or run spawn pull --force to merge (conflicts are marked in the files the usual git way). Pulling the same changes twice is refused for the same reason.

Open a pull request

spawn pr opens the session page, where Create PR publishes the agent’s commits as a pull request. This needs a session started from a git repository that’s connected to spawn as a project; otherwise use spawn pull and push from your machine. If a pull request already exists, spawn pr prints it.

Background agents

Hand Claude a GitHub issue or pull request and let it work without a terminal. Nothing is uploaded from your machine: it works from the repository of a connected project.

Terminal 
spawn fix https://github.com/acme/app/issues/42
spawn review acme/app#57 --prompt "Focus on the migration"
spawn logs -f
  • spawn fix has Claude fix the issue and open a pull request.
  • spawn review has Claude review the pull request.
  • spawn status shows where a session is and Claude’s latest message; spawn logs -f follows it until it finishes and prints the PR or review link.
  • The first time for a repository, spawn may ask for its project: --project <id or dashboard URL>. It remembers it after that.
Ctrl I