Install

spwn is a single CLI binary that runs a web server and opens its UI in your browser. Run it on your own machine, or deploy it as a long-lived server and open it from anywhere.

What you need

• macOS or Linux. spwn and its pane daemon, rmux, are unix programs.
• git. A project that is a git repository gets a worktree and branch per session. A folder that isn’t still works, but its sessions run in the folder itself.
• The claude CLI. spwn runs the same claude you’d run in a terminal; it never reimplements, re-uploads or proxies anything. You can sign in from spwn’s setup screen the first time you open it.

Install a release

1. Download spwn-<version>-<os>-<arch>.tar.gz from the latest release and unpack it.
2. It holds two binaries, spwn and rmux. Keep them in the same directory, and put that directory on your PATH.
3. Run spwn.

tar xzf spwn-0.1.3-darwin-arm64.tar.gz
mv spwn-0.1.3-darwin-arm64/{spwn,rmux} ~/.local/bin/
spwn

Bare spwn is the same as spwn serve: it binds 127.0.0.1:4317 and opens your browser. Add --no-open to skip the browser, or --port and --host to move it. See the CLI reference for every flag.

Note

Releases are cut on a maintainer’s machine, one platform per build (scripts/release.sh), so which <os>-<arch> tarballs exist depends on the release. If yours isn’t there, build from source.

Build from source

You need Rust, Node, and (on macOS) the Xcode Command Line Tools.

git clone https://github.com/spwn-gg/spwn && cd spwn
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
npm install
npm run build:app        # builds the SPA, then cargo build --release

The binary lands at backend/target/release/spwn, with the UI embedded in it. You still need an rmux it can find (see below): its minor version has to match the rmux-sdk dependency in backend/Cargo.toml (0.6.x today), because the SDK speaks exactly one wire version.

cargo install rmux --version 0.6.1 --locked

BUILD.md covers the dev loop and the Docker-based contributor environment.

Run it in Docker

For a single developer who wants spwn in a container with a home volume of its own:

docker run -d --name spwn \
  --restart unless-stopped \
  -p 127.0.0.1:4317:4317 \
  -v spwn-home:/home/spwn \
  ghcr.io/spwn-gg/spwn

Open http://localhost:4317. Nothing from your machine is mounted: the container has its own Claude login, its own clones and its own shells, all on the spwn-home volume. The port is published on 127.0.0.1 only, so nothing else on your network can reach it.

Inside the container spwn binds 0.0.0.0, so it requires an account and prints a one-time setup link on first boot:

docker logs spwn 2>&1 | grep -A3 'no account yet'

See Remote access for what that account means.

To upgrade, pull the new image and recreate the container. The volume carries everything over:

docker pull ghcr.io/spwn-gg/spwn
docker rm -f spwn

Then run the docker run command above again.

Caution

docker volume rm spwn-home deletes your Claude login and any session branches you never pushed or merged. Removing the container alone keeps them.

Deploy to Kubernetes with Helm

There is no published chart or image. Build the image, push it somewhere your cluster can pull from, and install the chart from a clone:

docker build -f deploy/Dockerfile -t registry.example.com/spwn:0.1.3 .
docker push registry.example.com/spwn:0.1.3

helm install spwn ./deploy/charts/spwn -n spwn --create-namespace \
  --set image.repository=registry.example.com/spwn
kubectl -n spwn port-forward svc/spwn 4317:80

image.repository is required; the tag defaults to the chart’s appVersion. Build for the architecture your nodes run. The pod binds 0.0.0.0, so the first boot prints a setup link: kubectl -n spwn logs deploy/spwn | grep -A3 'no account yet'.

The image carries spwn, rmux, claude, git and code-server. Ingress, storage, session pods, SSO and multi-tenant setups are in deploy/charts/spwn and values.yaml.

How spwn finds rmux

Every pane, shell and agent alike, runs in an rmux daemon that spwn launches. At startup spwn looks for the rmux binary in this order and takes the first that exists:

1. RMUX_SDK_DAEMON_BINARY, if set.
2. rmux in the same directory as the spwn executable (the release tarball layout).
3. /opt/homebrew/bin/rmux, /usr/local/bin/rmux, /usr/bin/rmux.
4. rmux on $PATH.
5. ~/.cargo/bin/rmux.

Agent binaries such as claude are found separately, from the agent definitions in ~/.spwn/agents (an override in Settings → Agents, then CLAUDE_BIN, then $PATH, then the usual install locations).

Upgrading

There is no self-updater.

• Release tarball: download the new one and replace both spwn and rmux, then restart spwn. On your own machine, restarting spwn doesn’t kill your panes: shells and agent sessions keep running in rmux and reattach with their processes intact.
• Docker: docker pull ghcr.io/spwn-gg/spwn, then recreate the container. See Run it in Docker. The volume survives; the panes don’t, because the rmux daemon lives in the container.
• Helm: build and push the new image, then helm upgrade with the new image.tag (or a chart whose appVersion names it). Panes don’t survive a pod restart either; agent sessions resume from their transcripts.

Next

Your first session walks through setup and starting an agent.