Deploy Space Agent: Desktop, Server, and Production Modes
Three ways to run Space Agent: a no-terminal desktop app, a personal Node.js server, and a zero-downtime production supervisor for shared team deployments.
Use this file to discover all available pages before exploring further.
Space Agent ships three distinct deployment modes to cover every scale of use — from a personal no-setup desktop app to a production supervisor that handles zero-downtime updates for a shared team server. Choose the mode that matches your environment, then graduate to a more capable one as your needs grow. All three modes run the same browser-first runtime; only the hosting wrapper changes.
Runtime parameters can be supplied in three ways, applied in this precedence order: (1) launch-time arguments (e.g. node space serve PORT=8080), (2) stored .env values written by node space set KEY=VALUE, then (3) process environment variables, and finally (4) schema defaults from commands/params.yaml. Use node space set to persist a value permanently so you do not have to repeat it on every start. Use launch-time arguments for one-off or deployment-specific overrides without touching the stored config.
The desktop app is the fastest way to get Space Agent running. It bundles the Node.js server, the browser frontend, and the Electron host into a single downloadable application. No terminal, no Node.js installation, and no configuration are required — open it and it works.
When launched, the desktop app starts the Space Agent server on a free loopback port assigned by the OS (PORT=0), then loads the resolved runtime URL in an Electron browser window. The entire stack — server and UI — runs as one local process. There is no network exposure by default.
The desktop app is ideal for personal, offline, or air-gapped use. Because it runs on a loopback port selected at startup, no firewall rules are needed.
The desktop app does not support node space supervise zero-downtime updates — to update, download and install the new release from GitHub Releases. Writable L1 and L2 customware is stored inside the app’s user-data directory. Use the personal server mode if you need CUSTOMWARE_PATH control over where that state lives.
Running Space Agent as a personal server gives you full control over configuration while keeping setup simple. This mode is suited for individual developers and home-lab setups where you want the server accessible from a browser without the Electron wrapper.
If you are the only person using this server, enable SINGLE_USER_APP to skip the login screen entirely. The server runs as an always-authenticated implicit user named user with virtual _admin access:
node space serve SINGLE_USER_APP=true
When SINGLE_USER_APP=true is set, no user creation step is needed. The implicit user principal has full admin access and does not require a password.
Use node space set to write a parameter permanently to the project .env file so it applies on every future start without needing to be passed on the command line:
node space set CUSTOMWARE_PATH=/srv/space/customware
Setting CUSTOMWARE_PATH before creating users or groups is important: the user and group commands resolve this stored parameter to decide where L1 and L2 files belong. If you move CUSTOMWARE_PATH after users exist, existing user data will not follow automatically.
For shared team servers and production deployments, node space supervise wraps the runtime in a zero-downtime supervisor that manages child processes, auto-updates from Git, and survives crashes with bounded restart backoff.
node space superviserequiresCUSTOMWARE_PATH to be set. This is the stable writable state boundary that persists across source-release swaps during auto-updates. Set it before creating any users or groups:
node space set CUSTOMWARE_PATH=/srv/space/customware
Running node space supervise without CUSTOMWARE_PATH configured will cause it to exit with an error. The supervisor cannot safely swap releases without a writable state directory that is external to the source checkout.
The supervisor binds the public HOST and PORT itself and starts real node space serve children on private loopback ports (HOST=127.0.0.1 PORT=0). HTTP requests and WebSocket upgrade streams are proxied to the active child. During an update:
A staged release is cloned into <projectRoot>/supervisor/releases/<revision>/
npm install --omit=optional runs inside the staged release
A replacement child starts and must print its listening URL and pass /api/health
Live traffic drains from the old child; the new child takes over
If the replacement fails health checks it is discarded and retried on the next interval
The OS process title of the supervisor is set to space-supervise so it is easy to distinguish from child server processes in system monitoring tools.
The supervisor checks the configured Git remote for a newer revision on a timer. The default interval is 300 seconds (5 minutes). Adjust or disable it with --auto-update-interval:
node space supervise --auto-update-interval 300 CUSTOMWARE_PATH=/srv/space/customware
Update intervals are non-overlapping. The next timer is scheduled only after the current update attempt finishes or fails, so a slow network or a large release cannot cause update attempts to pile up.
For high-traffic deployments, set WORKERS to run multiple HTTP worker processes. The supervisor passes this through to child servers:
node space supervise HOST=0.0.0.0 PORT=3000 WORKERS=4 CUSTOMWARE_PATH=/srv/space/customware
With WORKERS > 1, a clustered primary process plus N worker processes handle requests. Debounced Git history commits for L1 and L2 roots are scheduled only by the primary to keep commit state authoritative.