CLI & environment
spwn has one real command, serve, and two small helpers that hooks call. Everything else
happens in the browser.
spwn / spwn serve
Section titled “spwn / spwn serve”Start the web server and open the UI in your browser. Bare spwn is exactly spwn serve
with its defaults.
spwnspwn serve --port 4317 --host 127.0.0.1 --no-open| Flag | Default | What it does |
|---|---|---|
--port <port> |
4317 |
Port to listen on. |
--host <addr> |
127.0.0.1 |
Address to bind. Must be an IP address. Use 0.0.0.0 to expose spwn on your network or through a container’s published port. Binding beyond loopback turns accounts on unless you pass --no-auth. |
--no-open |
off | Don’t open the browser. |
--auth |
off | Require an account, even on localhost. The first boot prints a setup link. Conflicts with --no-auth. |
--no-auth |
off | Don’t require an account, even when bound beyond localhost. Anyone who can reach the port gets a shell on this machine; put your own gate in front. |
-h, --help |
Print help. | |
-V, --version |
Print the version. |
An invalid --host exits with status 2. See Remote access for how
the flags, SPWN_AUTH and the bind address combine.
Hook helpers
Section titled “Hook helpers”These two aren’t listed in --help. They run before the server machinery, as short-lived
processes, and only make sense inside a hook. Hooks get the binary’s path in $SPWN_BIN,
so "$SPWN_BIN" prompt … works even when spwn isn’t on PATH.
spwn prompt
Section titled “spwn prompt”spwn prompt [--multi] [--header TEXT] "Question?" [option ...]Asks the user a question in the UI and blocks until they answer. With no options it’s a
Yes/No confirm. It prints the chosen label and exits 0; exits 2 if the prompt was
declined (for example in a headless run); exits 3 on bad arguments or outside a hook. See
Talking back to spwn and the hooks reference.
spwn checkpoint
Section titled “spwn checkpoint”spwn checkpoint <turn-uuid>Snapshots the session’s worktree for the Timeline. The default session-turn hook calls it;
it reads SPWN_SESSION_ID and SPWN_WORKTREE, and does nothing (exit 0) when either is
unset. See the hooks reference.
Environment variables
Section titled “Environment variables”Variables spwn reads when it runs. Set them in the shell that starts spwn, in Compose’s
environment:, or through the Helm chart’s values and envFrom.
Server and access
Section titled “Server and access”| Variable | What it does |
|---|---|
SPWN_AUTH |
How accounts work: off, on (or local), proxy, oidc. --auth and --no-auth win over it; unset, it follows the bind address. proxy and oidc need a build with the enterprise feature. |
SPWN_PUBLIC_URL |
The URL people actually visit, e.g. https://spwn.example.com. Set it behind any proxy: it’s what Origin is checked against when the proxy rewrites Host, an https:// value marks cookies Secure, and it’s the base of the setup link and the OIDC redirect. |
SPWN_SETUP_TOKEN |
Use this as the first-account setup token instead of minting one. |
SPWN_AUTH_PROXY_HEADER |
proxy mode, required: the header carrying the user’s identity, e.g. X-Auth-Request-Email. |
SPWN_AUTH_PROXY_FROM |
proxy mode: comma-separated addresses or CIDR ranges allowed to assert that header. Unset means any peer. |
SPWN_OIDC_ISSUER |
oidc mode, required: the provider’s issuer URL. |
SPWN_OIDC_CLIENT_ID |
oidc mode, required. |
SPWN_OIDC_CLIENT_SECRET |
oidc mode: the client secret. |
SPWN_OIDC_CLIENT_SECRET_FILE |
oidc mode: read the client secret from this file instead. Wins over SPWN_OIDC_CLIENT_SECRET. |
SPWN_OIDC_SCOPES |
oidc mode: scopes beyond openid, comma- or space-separated. Default email,profile. |
SPWN_OIDC_AUTO_PROVISION |
oidc mode: 1/true/on/yes creates an account for anyone the provider admits. |
SPWN_IDLE_ENDPOINT |
1/true/on/yes serves GET /api/idle without a credential: pane and session counts and whether the instance is idle, for an autoscaler. Off by default. |
SPWN_IDE_IDLE_MINUTES |
Stop a browser editor nobody has used for this many minutes. Default 30; 0 never stops them. |
SPWN_IDE_DEBUG |
Set to anything to log the editor proxy’s connection chatter to stderr. |
Binaries and paths
Section titled “Binaries and paths”| Variable | What it does |
|---|---|
RMUX_SDK_DAEMON_BINARY |
The rmux daemon to launch. When unset, spwn looks next to its own executable, then in /opt/homebrew/bin, /usr/local/bin, /usr/bin, then $PATH, then ~/.cargo/bin (see Install). |
CLAUDE_BIN |
Path to claude. Checked after the override in Settings → Agents and before $PATH. |
CODEX_BIN, GEMINI_BIN |
The same, for the codex and gemini agent definitions. |
CLAUDE_CONFIG_DIR |
Where Claude Code keeps its config and transcripts. spwn reads (never writes) $CLAUDE_CONFIG_DIR/projects and $CLAUDE_CONFIG_DIR/.claude.json; unset, ~/.claude and ~/.claude.json. |
SHELL |
The shell new shell panes run. Default /bin/zsh. |
ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN |
spwn never uses these, claude does. If either is non-empty, spwn reports Claude as signed in and the setup screen skips that step. |
spwn keeps its own data (projects, settings, checkpoints, auth, workflow state) in
~/Library/Application Support/gg.spwn.spwn/ on macOS and ~/.local/share/gg.spwn.spwn/ on
Linux ($XDG_DATA_HOME/gg.spwn.spwn/ when that’s set).
Set by spwn, for hooks
Section titled “Set by spwn, for hooks”spwn sets these in a hook’s environment; you don’t set them yourself. Most describe the
session: SPWN_EVENT, SPWN_PROJECT_DIR, SPWN_WORKTREE, SPWN_BRANCH,
SPWN_BASE_BRANCH, SPWN_SESSION_ID, SPWN_TERMINAL_ID, SPWN_TURN_UUID, SPWN_EXEC.
Others are plumbing (SPWN_BIN, SPWN_PROMPT_SOCK), belong to particular events
(SPWN_SESSION_WORKTREE, SPWN_TRIAL_WORKTREE, SPWN_START_POINT), or come from workflows
(SPWN_WORKFLOW, SPWN_WORKFLOW_RUN_ID, SPWN_WORKFLOW_STATUS). The
hooks reference says what each one holds and when it’s set.
Development only
Section titled “Development only”SPWN_BACKEND tells the Vite dev server (npm run dev) where to proxy /api and /ws.
Default http://127.0.0.1:4317. The release binary doesn’t read it.