Space Agent provides three commands for running the server:Documentation Index
Fetch the complete documentation index at: https://mintlify.com/agent0ai/space-agent/llms.txt
Use this file to discover all available pages before exploring further.
serve starts a direct Node process, supervise wraps it with a production-ready reverse-proxy that handles zero-downtime updates and crash restarts, and update pulls the latest source from the configured Git repository. For local development serve is enough; for long-running production source checkouts supervise is the recommended entry point.
serve
node space serve starts the local Node server that serves the browser app, page shells, /mod/... assets, and /api/... endpoints. It is a single command with no subcommands — all configuration is passed as PARAM=VALUE launch overrides or read from the project .env.
Usage
Parameter override syntax
Any parameter defined incommands/params.yaml can be overridden at launch using PARAM=VALUE positional arguments. The resolution order from highest to lowest priority is:
- Launch arguments —
PARAM=VALUEpassed directly tonode space serve - Stored
.envvalues — written bynode space set KEY=VALUE - Process environment variables — inherited from the shell
- Schema defaults — defined in
commands/params.yaml
Clustered mode
SettingWORKERS greater than 1 starts a clustered HTTP worker pool. One authoritative primary process owns shared filesystem and auth state; the remaining workers handle HTTP requests in parallel.
htop can identify each role:
| Role | Process title |
|---|---|
| Single-process | space-serve |
| Clustered primary | space-serve-p |
| Clustered worker N | space-serve-w<N> |
supervise
node space supervise runs Space Agent behind a production-ready reverse-proxy supervisor. It manages replaceable space serve child processes, stages source-checkout updates in separate release directories, and switches traffic to a replacement child only after a health check passes. It also restarts the active child on crash with bounded backoff.
supervise requires CUSTOMWARE_PATH — a stable writable directory that persists across source-release swaps and is shared by all child processes.
Usage
Supervisor flags
Git branch to watch for source updates. Defaults to the current or remembered checkout branch.
Git remote URL to watch for updates. Overrides
GIT_URL, which otherwise overrides the local origin remote URL.Supervisor state directory for release staging and auth key storage. Defaults to
<projectRoot>/supervisor.Seconds between zero-downtime source update checks. Defaults to
300 (5 minutes). Set to 0 or any value ≤ 0 to disable update checks and keep crash-restart supervision only.Seconds to wait for a replacement child to become healthy before discarding it. Defaults to
30.Seconds of no proxied traffic before an old child process is cut off during a handover. Defaults to
1.Maximum seconds to keep an old child alive during drain regardless of traffic. Defaults to
30.Initial crash-restart backoff in seconds. Defaults to
1 and caps at 30.How it works
Supervisor binds the public port
The supervisor process binds to the configured public
HOST and PORT and sets its OS process title to space-supervise. Child space serve processes always run on private loopback HOST=127.0.0.1 PORT=0.First child starts
The supervisor launches a
space serve child with the normalized CUSTOMWARE_PATH, forced loopback bind, and all other PARAM=VALUE arguments passed through unchanged.Periodic update checks (when enabled)
Every
--auto-update-interval seconds the supervisor checks the watched Git remote and branch for a newer revision. Update attempts are non-overlapping — the next check is only scheduled after the current one finishes or fails.Staged release
When a new revision is found, the supervisor clones it into a release directory under
<state-dir>/releases/<revision>/ and runs npm install --omit=optional inside the staged checkout.Health-gated promotion
A replacement child is started from the staged release on a private loopback port. The supervisor waits for the child to print its listening URL and pass
/api/health. Unhealthy children are stopped and discarded; the active child keeps serving.Environment variables
Optional Git repository URL for update checks and staged release clones. Remote resolution order:
--remote-url flag → GIT_URL env → local origin remote URL → canonical fallback.Personal access token for fetching from private GitHub repositories. Used by both
supervise update checks and node space update. When absent, no GitHub auth header is sent.update
node space update fetches and applies source-checkout updates from the configured Git update repository. It is intended for source checkouts only and does not update packaged Electron apps.
Usage
Update flag
Force update of the named branch instead of inferring the current branch or positional target.
Remote resolution order
Before fetching,update resolves the update repository in this order and pins origin to the result:
GIT_URLenvironment variable (or.envvalue)- Local
originremote URL - Canonical Space Agent repository fallback
Target resolution
| Argument | Behavior |
|---|---|
| (none) | Fast-forwards the current or recoverable branch from origin |
--branch <branch> | Reattaches and fast-forwards the named branch |
<branch> positional | Same as --branch when the name matches a remote branch |
<version-tag> | Moves the current or recovered branch to that exact tag revision |
<commit> | Moves the current or recovered branch to that exact commit hash |
When the checkout is in detached HEAD,
update attempts to reconnect using the last remembered branch or the remote default branch before fast-forwarding. If neither is available, the command exits with an error rather than silently doing nothing.