Installation — SpaceApp Docs

Universal installation#

You need a Linux, macOS or Windows 11 computer (x64 or arm64) with at least 4 CPU cores, 8 GB of RAM and 6.5 GiB of free disk, an internet connection, and Node.js 20.11 or newer. Docker is also required, but the launcher installs and starts it for you when it is missing.

Run this as the user who will own the installation. On Windows, use Command Prompt (see Windows 11):

npx --yes run-spaceapp@latest install

The command runs these steps in order:

Asks five setup questions and shows a plan. Nothing changes until you answer y.
Checks CPU, memory and free disk, then installs and starts Docker if it is missing or stopped.
Checks Node.js, Docker's allocation, the Docker CLI, Compose and the engine, printing one PASS or FAIL line per check. A failed check stops the install with Installation stopped before downloading images.
Downloads the SpaceApp images.
Starts the services and waits up to 10 minutes for them to become ready.
Creates a one-time setup token, prints it, and opens the setup page in your browser.

The setup questions#

Press Enter to accept the default shown in brackets. This is the wizard from a 1.1.1 test on a 4-CPU, 8 GB Linux virtual machine, shown with the default answers and the default installation root:

Which installation profile?
  [1] auto (small; 4 CPUs, 7.7 GiB RAM, 18.2 GiB free)
  [2] small (SpaceApp + OpenCode; no background workflows or managed browser)
  [3] medium (background workflows and integration workers)
  [4] large (workflows + managed browser; larger resource limits)
  [5] light (legacy compatibility)
  [6] standard (legacy compatibility)
Select 1-6 [1]:
Which access mode?
  [1] isolated (recommended; no host access)
  [2] host-root (Linux only; CLI sessions can read and modify the whole host)
Select 1-2 [1]:
Enable companion integrations (Claude Code, browser companions)? [y/N]
Enable anonymous usage telemetry? [y/N]
Open the web application when installation completes? [Y/n]
SpaceApp setup plan:
  - Installation root: /home/alice/.config/spaceapp
  - Runtime image version: not installed -> 1.1.1
  - Profile: auto (small)
  - Access mode: isolated
  - Companions: disabled
  - Telemetry: disabled
  - Docker installation: automatic if missing
  - Open browser afterwards: yes
  - Future refreshes preserve data, workspaces, credentials, secrets, and persistent Docker volumes.
Apply this plan? [y/N] y

For a first install, keep auto, isolated, no companions, and choose telemetry as you prefer (the default is No). Windows asks two more questions; see Windows 11.

What a successful install prints#

The rest of the same Linux run, shortened: the disk-space lines and Docker's own image and container progress are left out, and the token is replaced.

Launcher version: 1.1.1
Runtime image version: not installed -> 1.1.1
Profile: not configured -> small
Access: not configured -> isolated
Future refreshes preserve data, workspaces, credentials, secrets, and persistent Docker volumes.
Selected profile: small (7.7 GiB system memory detected).
SpaceApp installation root: /home/alice/.config/spaceapp
PASS Node.js: v22.23.1
PASS Configuration: Prepared installation configuration
PASS CPU: 4 available; 4 required
PASS Memory: 7.7 GiB available; 7 GiB usable (8 GB-class system) required
PASS Docker memory: 7.7 GiB allocated; 3 GiB required for small
PASS Docker CPU: 4 allocated; 4 required
PASS Docker CLI: available
PASS Docker Compose: available
PASS Docker Engine: available
Waiting up to 10 minutes for SpaceApp services to become ready...
SpaceApp is ready at http://127.0.0.1:4911
One-time setup token: <43 random characters>
Paste it into the "One-time setup token" field in the page that opens.
It expires in 15 minutes and stops working after the first owner is created.
If it expires, run: npx --yes run-spaceapp@latest owner rotate-setup-token
Next: open the Getting Started room and use OpenCode. A working free model is selected on first launch.
Optional providers: "npx --yes run-spaceapp@latest credentials set <provider>".

Keep this terminal open: you need the token in the next step. Never share it or paste it anywhere except the setup page.

Where the browser opens#

The launcher opens http://127.0.0.1:4911 with your default browser on Linux (xdg-open) and macOS (open), and with Microsoft Edge on Windows. The first page is Create your Space owner; continue with Your first session.

If no browser opens (a headless machine, --no-open, or the window was closed), the launcher prints Could not open SpaceApp automatically. Open http://127.0.0.1:4911 manually. Open that address yourself, or run:

npx --yes run-spaceapp@latest open

The address only works on the machine running SpaceApp. Another computer's 127.0.0.1 points to itself, not to your host; see Remote & mobile access.

How long it takes#

In the 1.1.1 release tests (4-CPU, 8 GB virtual machines with Docker already running and the SpaceApp images already downloaded), the install command finished in about 16 seconds on Linux, 25 seconds on macOS and 50 seconds on Windows 11. Those runs skipped the two slowest steps of a real first install: installing Docker and downloading the images. Both depend on your connection and machine, so expect a first install to take noticeably longer, and longer again on Windows if WSL2 needs a restart.

While the services start, the launcher prints Still waiting for SpaceApp services (… seconds elapsed; up to 10 minutes)... with the container status every 30 seconds, and recent logs every two minutes. If the application is not ready after 10 minutes, the install stops, rolls back the new containers and keeps your data volumes; see Troubleshooting.

About the command#

The --yes flag belongs to npx and accepts npm's package-execution prompt. It does not replace SpaceApp's plan confirmation, Docker Desktop license acceptance, OS elevation or destructive-operation confirmations.

The optional global launcher is separate:

npm install -g run-spaceapp
spaceapp help

A global install is not required. Keeping @latest in the universal command resolves the current npm release rather than assuming a locally installed launcher is current. For reproducibility, use an explicitly chosen published version after consulting its release notes.

Requirements and resource profiles#

Required: Node.js 20.11+, a supported OS/architecture, sufficient resources, network access to required package/image registries and a working Docker Engine with Compose. The launcher checks Docker separately from the Node prerequisite needed to start npx.

Profile	CPU cores	Usable RAM	Fresh free disk	Docker allocation	Services
`small`	4	7 GiB	6.5 GiB	3 GiB RAM, 4 CPUs	Core app, CLI/OpenCode and PostgreSQL.
`medium`	4	11 GiB	8 GiB	5 GiB RAM, 4 CPUs	Small plus background workflow/integration workers.
`large`	8	15 GiB	11 GiB	7 GiB RAM, 4 CPUs	Medium plus managed Chromium and larger limits.

An 8 GB-class machine is the minimum class for small; 8 CPUs, 16 GB RAM and 25 GiB free disk are a useful recommended starting point for browser sessions and several active agents. Workload, project size and optional services can require more.

auto selects the largest profile fitting CPU, RAM and disk, then checks Docker's allocation. Docker Desktop's limits can be lower than host totals, so the Docker allocation column is checked separately. On the 8 GB test machines, Docker Desktop reported 3.7 GiB (Windows) and 3.8 GiB (macOS), enough for small. Existing installs retain their profile unless explicitly changed. light and standard remain compatibility profiles.

npx --yes run-spaceapp@latest install --profile small
npx --yes run-spaceapp@latest install --profile medium
npx --yes run-spaceapp@latest install --profile large

Limits are maxima, not all reserved memory at startup. Small disables background integration workers and managed browsers; it does not grant fewer filesystem permissions or redefine the application's warm-room policy. Profiles are not promises of a specific number of simultaneous AI calls.

Fresh disk thresholds are not preallocation. Upgrades estimate missing image layers, a database checkpoint and 0.5 GiB reserve. Cached target images require no additional image download space. Shared layers are excluded when metadata permits; unknown metadata uses a conservative estimate. Space is checked again after pull and before cutover. The launcher does not delete user volumes, images, backups or workspaces just to make space.

Linux#

Supported automatically: Ubuntu, Debian, Fedora, RHEL and CentOS (Docker's official repositories) and Arch-family systems such as CachyOS (docker and docker-compose through pacman). On other distributions, install Docker Engine and the Compose plugin yourself first.

Install Node.js 20.11 or newer. Distribution packages are often older, so check before you continue; the LTS release from nodejs.org or a version manager works:
bash
```
node --version
```
Run the universal command in a terminal as your normal user. Do not prefix it with sudo: that can put the installation under root's configuration directory instead of yours and runs everything as root.
bash
```
npx --yes run-spaceapp@latest install
```
Answer the setup questions and approve the plan.
If Docker is missing, the launcher prints Docker Engine is required and is not installed. Installing it for ubuntu... (with your distribution's ID) and runs the package commands through sudo, so expect a password prompt. It then starts the docker service.

If your user cannot use Docker yet, the launcher explains the trade-off and adds you to the docker group:

Docker's official post-install flow uses the docker group.
Membership grants root-level privileges on this host.
Adding alice to the docker group automatically and continuing.
Docker Engine is ready. Continuing SpaceApp installation with the new group membership...

The install continues in the same command. Log out and back in afterwards so that new terminals also have the group.

When the install finishes, your default browser opens the setup page.

If Docker is installed but stopped, the launcher prints Docker Engine is installed but is not ready. Starting it now... and continues after Docker Engine is ready. On an unsupported distribution it stops with Automatic Docker Engine installation is not yet supported for Linux distribution "<id>". Install Docker Engine and the Compose plugin from https://docs.docker.com/engine/install/ and rerun the same command.

On a server without a desktop, skip the browser step:

npx --yes run-spaceapp@latest install --no-open

The app still binds to 127.0.0.1 only. To finish setup from your laptop, forward the port over SSH and open http://127.0.0.1:4911 on the laptop:

ssh -L 4911:127.0.0.1:4911 alice@your-server

Linux containers run on the host Docker Engine; SpaceApp does not create a second full guest VM.

macOS#

Apple Silicon Macs use arm64 images and Intel Macs use amd64 images. Docker Desktop runs them in its own managed Linux environment.

Install Node.js 20.11 or newer, for example the LTS installer from nodejs.org or brew install node, then check it in Terminal:
bash
```
node --version
```
Run the universal command in Terminal and approve the plan:
bash
```
npx --yes run-spaceapp@latest install
```
If Docker Desktop is missing, approving the plan (Docker installation: automatic if missing) lets the launcher install it. It prints:
text
```
Docker Desktop is required and is not installed.
Installing Docker Desktop for macOS automatically as approved in setup plan...
Downloading Docker Desktop from Docker's official distribution service...
Docker Desktop signature and macOS trust verification passed.
macOS administrator authorization is required to install Docker Desktop.
Enter the password for your Mac administrator account—not a Docker or SpaceApp password.
Characters are not displayed while you type. SpaceApp does not read, store, or log this password.
```
Type your Mac login password (an administrator account is required) and press Enter. The launcher checks the download's code signature and Gatekeeper approval before running it, and installs Docker Desktop with its license accepted. Read the Docker Subscription Service Agreement first: Docker Desktop's terms are separate from SpaceApp's license, and some organizations need a paid Docker subscription.
The launcher opens Docker Desktop and waits up to 10 minutes for it. If Docker Desktop shows a first-run window, complete or skip it. The install continues after Docker Desktop is ready.
When the install finishes, your default browser opens the setup page.

If Docker Desktop is installed but not running, the launcher prints Docker Desktop is installed but is not running. Starting it now... and continues. If it is still not ready after 10 minutes, the launcher stops with Docker Desktop did not become ready after 10 minutes. Complete any Docker Desktop prompt, then run "npx --yes run-spaceapp@latest install" again. Open Docker Desktop from Applications, finish any prompt, wait until it reports that the engine is running, and run the same command again.

Host RAM/disk and Docker's allocation both matter. If the Docker memory check fails, raise the memory limit in Docker Desktop's resource settings and run the command again.

Windows 11#

Make sure hardware virtualization is enabled in the firmware (BIOS/UEFI) settings; it is often on already. Docker Desktop needs it for WSL2.
Install Node.js 20.11 or newer, either the LTS installer from nodejs.org or:
bat
```
winget install OpenJS.NodeJS.LTS
```
Open a new Command Prompt (or the Command Prompt profile in Windows Terminal) so it sees Node.js, check it, and run the universal command:
bat
```
node --version
npx --yes run-spaceapp@latest install
```
PowerShell with a restricted execution policy blocks npm's npx.ps1 before SpaceApp starts. Use Command Prompt, or call the .cmd shim explicitly; do not change the machine's execution policy as a workaround:
powershell
```
npx.cmd --yes run-spaceapp@latest install
```
Windows asks two extra questions. When Docker is not found: Docker Engine was not detected. Include automatic Docker installation? [Y/n] (keep Yes). After the plan: Allow an unattended continuation for this same version on the next Windows RunOnce run (expires in 24h)? [y/N]. Answer y if a restart is likely (a PC without WSL2), so the resumed install does not ask the questions again; the permission is used once and expires after 24 hours.
If WSL2 is missing, the launcher prints Installing the Windows Subsystem for Linux 2 support required by Docker Desktop... and Windows shows a UAC prompt; approve it. When WSL2 needs a restart, the launcher registers a one-time resume and asks first:
text
```
Windows must restart to finish enabling WSL2.
SpaceApp is scheduled to resume automatically after you sign in.
Restart Windows in 15 seconds and continue SpaceApp after sign-in? [y/N]
```
Save your work and answer y (or n to restart later yourself). After you sign back in, the same install continues automatically in Command Prompt; you do not type the command again.
If Docker Desktop is missing, the launcher installs it through Windows Package Manager with manifest hash verification (Installing Docker Desktop through Windows Package Manager with manifest hash verification...). If that is unavailable, it downloads Docker's signed installer and checks its Authenticode signature first. Approve any UAC prompt. Docker Desktop's license terms apply, as on macOS.

The launcher then starts Docker Desktop and prints:

Opening Docker Desktop for its first-run setup.
If Docker shows "Welcome to Docker", select "Skip" in the top-right (or sign in), and accept any remaining Docker prompt.
Keep this terminal open; SpaceApp will continue automatically when Docker is ready (up to 10 minutes).

Do what it says in the Docker Desktop window and leave Command Prompt open. The install continues after Docker Desktop is ready.

When the install finishes, Microsoft Edge opens the setup page.

If Docker Desktop is not ready after 10 minutes, the launcher stops with Docker Desktop did not become ready after 10 minutes. Open Docker Desktop and complete its first-run setup (select "Skip" on "Welcome to Docker" or sign in), restart Windows if requested, then run "npx --yes run-spaceapp@latest install" again. Open Docker Desktop from the Start menu, finish its prompts, wait until it reports that the engine is running, then run the same command again.

Docker Desktop uses its WSL2 Linux environment. SpaceApp does not install another full independent VM. A large Docker disk limit is a maximum sparse-disk size, not immediate host allocation; reclaimed Docker space may need Desktop's compact/reclaim operation to shrink the visible host file.

Installation identity and paths#

Use the same OS account and installation root for later commands.

Platform	Default root
Linux	`$XDG_CONFIG_HOME/spaceapp` or `$HOME/.config/spaceapp`
macOS	`$HOME/Library/Application Support/SpaceApp`
Windows	`%APPDATA%\SpaceApp`

Set SPACEAPP_HOME to an absolute path to select a separate installation root. Keep that variable consistent across install, status, backup and recovery. Changing it can make an existing installation appear missing because the launcher is inspecting a different root.

The root holds configuration, secrets and backup-related files. Persistent Docker volumes hold application/database/provider state. Registered host project contents remain separate. Do not infer that copying one directory copies the whole installation or every provider login.