Running Space Agent in production is straightforward once you understand its two-layer model: the source checkout provides the firmware (L0), while a separate writable directory — controlled byDocumentation 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.
CUSTOMWARE_PATH — holds all group and user state. Keeping these apart means you can update the application code without touching anyone’s data, and node space supervise handles that handoff automatically with zero-downtime traffic switching.
Full Production Walkthrough
Clone and install
Clone the repository and install Node.js dependencies. No build step is required — Space Agent runs directly from source.Verify the installation by checking the version:
Set CUSTOMWARE_PATH
Before creating any users or groups, set Create the directory and give it to your service account:
CUSTOMWARE_PATH to an absolute directory outside the source checkout. This is where all writable L1 (group) and L2 (user) state lives. When you later update the source checkout with node space update, user data at this path is never touched.Setting
CUSTOMWARE_PATH via node space set writes it to the project .env file so every subsequent serve, supervise, and user/group CLI command picks it up automatically. A launch-time override (node space serve CUSTOMWARE_PATH=...) only applies to that single process.Create an admin user
Create your first admin account. The You can change the password at any time:
--groups _admin flag adds the user to the built-in _admin group, which grants full read/write access across all L1 and L2 paths.Configure server parameters
Set the network bind address, port, and worker count in the project
.env. These values persist across restarts.WORKERS=4 runs a clustered runtime with one authoritative primary process (which owns watchdog and state) plus four HTTP workers handling requests in parallel. For a single-CPU or low-traffic machine, WORKERS=1 (the default) keeps everything in one process.Review all current parameter values at any time:Start with the supervisor
For production use Common supervisor options:The supervisor normalizes
node space supervise, which runs a stable reverse-proxy in front of replaceable space serve child processes. It checks for source updates every five minutes by default and performs a zero-downtime switch: new traffic routes to the replacement child only after it passes a readiness check.CUSTOMWARE_PATH to an absolute path before injecting it into every child process, so all release checkouts share the same writable roots regardless of where the supervisor itself is started from.The supervisor process sets its OS title to
space-supervise, while child processes appear as space-serve, space-serve-p (clustered primary), or space-serve-w1 … space-serve-wN (clustered workers). These titles make it easy to identify processes in htop or ps.Verify the deployment
Open a browser and navigate to your server’s address. You should see the Space Agent login screen. You can also check the health endpoint directly:A successful response confirms the server is running and accepting requests. Log in with the admin credentials you created in step 3 and open
/admin to confirm admin mode is accessible.Additional Configuration
CUSTOMWARE_PATH and update safety
CUSTOMWARE_PATH defaults to an empty string. When it is empty, all writable L1 and L2 state lives inside the source checkout at app/L1/ and app/L2/. That is fine for local development or a single-person installation, but it means an update that replaces the source checkout directory would touch user data. For any server where updates matter, always point CUSTOMWARE_PATH to a directory outside the checkout before creating users.
When CUSTOMWARE_PATH is set to an absolute path, the logical paths resolve as follows:
| Logical path | On-disk location |
|---|---|
L0/... | <repo>/app/L0/... (read-only firmware) |
L1/<group>/... | CUSTOMWARE_PATH/L1/<group>/... |
L2/<username>/... | CUSTOMWARE_PATH/L2/<username>/... |
node space update (or node space supervise’s automatic update) only touches the source checkout. All group configuration and user data at CUSTOMWARE_PATH is never modified by an update.
Disabling background file watching
In container environments the defaultfs.watch listeners and periodic reconcile loop can produce unwanted noise. Set CUSTOMWARE_WATCHDOG=false to disable background watching while keeping startup indexing and the explicit clustered mutation path active:
Per-user disk quotas
USER_FOLDER_SIZE_LIMIT_BYTES caps each user’s L2/<username>/ folder on disk. Set to 0 (the default) to disable. For example, to cap each user at 500 MB:
Git backend preference
For production use, prefer thenative Git backend when git is installed on the host. It falls back to isomorphic automatically when native Git is unavailable:
auto mode already follows this fallback order (native -> isomorphic), so you only need to set this explicitly if you want to force one backend for testing or troubleshooting.
GitHub token for private update sources
If your production instance pulls from a private GitHub repository duringnode space update or supervised auto-updates, set SPACE_GITHUB_TOKEN in the environment before running the supervisor:
Development server
For local development and testing, usenpm run dev instead of node space serve. It starts the server with auto-reload on source changes and can attach a VS Code debugger to the spawned process:
server/ code. It launches the same watcher and auto-attaches to the spawned node space serve process across restarts.
Desktop app (zero-config single-user)
If you only need a personal installation with no server management, download the latest desktop app from GitHub Releases. It packages everything into one app with no terminal required — the server runs locally withSINGLE_USER_APP=true so all requests resolve to an implicit admin principal without any login step.