# SpaceApp: Installation, CLI Reference and Recovery

> A version-aware operational guide for owners and AI agents.

Reviewed: 2026-10-14. Command inventory and syntax checked against the published npm package `run-spaceapp` 1.1.4 (`npx --yes run-spaceapp@1.1.4 help`, unchanged from 1.1.1). Example terminal output comes from the 1.1.1 release tests on Linux, macOS and Windows 11 virtual machines and is shortened where marked. The npm latest tag may change after this date. Inspect the selected launcher's help and release notes before relying on version-specific behavior.

Index: https://spaceapp.dev/llms.txt
Agents: https://spaceapp.dev/llms-agents.txt
Architecture: https://spaceapp.dev/llms-architecture.txt
Generated launcher help: https://spaceapp.dev/docs/cli/

## 1. 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](#windows-11)):

```bash
npx --yes run-spaceapp@latest install
```

The command runs these steps in order:

1. Asks five setup questions and shows a plan. Nothing changes until you answer `y`.
2. Checks CPU, memory and free disk, then installs and starts Docker if it is missing or stopped.
3. 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.`
4. Downloads the SpaceApp images.
5. Starts the services and waits up to 10 minutes for them to become ready.
6. 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:

```text
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](#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.

```text
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](/docs/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:

```bash
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](/docs/remote-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](/docs/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:

```bash
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.

## 2. 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.

```bash
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.

## 3. 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.

1. 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
   ```

2. 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
   ```

3. Answer the setup questions and approve the plan.
4. 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.
5. If your user cannot use Docker yet, the launcher explains the trade-off and adds you to the `docker` group:

   ```text
   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.
6. 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:

```bash
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:

```bash
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.

## 4. macOS

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

1. 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
   ```

2. Run the universal command in Terminal and approve the plan:

   ```bash
   npx --yes run-spaceapp@latest install
   ```

3. 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](https://www.docker.com/legal/docker-subscription-service-agreement/) first: Docker Desktop's terms are separate from SpaceApp's license, and some organizations need a paid Docker subscription.
4. 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.`
5. 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.

## 5. Windows 11

1. Make sure hardware virtualization is enabled in the firmware (BIOS/UEFI) settings; it is often on already. Docker Desktop needs it for WSL2.
2. Install Node.js 20.11 or newer, either the LTS installer from nodejs.org or:

   ```bat
   winget install OpenJS.NodeJS.LTS
   ```

3. 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
   ```

4. 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.
5. 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.
6. 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.
7. The launcher then starts Docker Desktop and prints:

   ```text
   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.`
8. 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.

## 6. 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.

## 7. Create the owner account

SpaceApp has one owner account, and there is no default password. The first page, **Create your Space owner**, asks for:

- **Owner email**: the address you will sign in with.
- **One-time setup token**: the value printed by the installer on the line `One-time setup token:`. The field hides what you paste.
- **New password** and **Confirm password**: at least 12 characters.

![The Create your Space owner page that opens after installation, with the owner email and one-time setup token fields](/docs-media/owner-setup-page.webp "The first page after a 1.1.1 install on Linux. The line above Owner email shows when the token expires, in your local time.")

The setup token proves that the person creating the owner can read the installer's terminal on the host. The installer creates a fresh random token at the end of every successful install while no owner exists. It is valid for 15 minutes, works once, and stops working as soon as the owner is created. Enter it only on this page; never put it in a prompt, a chat, a screenshot, an issue or canonical memory.

Select **Create owner account**. SpaceApp signs you in and opens the setup wizard.

If the token has expired, or you closed the terminal before copying it, create a new one on the host:

```bash
npx --yes run-spaceapp@latest owner rotate-setup-token
```

It prints `New one-time setup token: …` and `It expires in 15 minutes and only works before the first owner is claimed.` Paste the new value into the page; reload it to see the new expiry time. Rotation is refused once an owner exists; running `install` again while no owner exists also prints a fresh token.

A lost owner password uses a different operation. The new password is read with masked input:

```bash
npx --yes run-spaceapp@latest owner reset-password
```

## 8. The Getting Started room and OpenCode

After sign-in, the **Setup & connections** wizard opens with four steps: Welcome, Tools, Connections and Ready. It explains rooms (separate workspaces for projects), panes (a CLI, Chat or Browser inside a room) and docks, and recommends **OpenCode** as the first tool. You can select **Finish for now** at any point and reopen the wizard later from Help → Setup wizard.

![The Setup & connections wizard shown after the owner account is created](/docs-media/setup-wizard.webp "Setup & connections, step 1 of 4. Finish for now closes it without cancelling a running CLI check.")

SpaceApp creates a room named **Getting Started** for you and selects it first; it is listed in the Rooms dock on the left. Start there. If the room has no OpenCode pane, use **Create** in the top bar to add a CLI pane and choose OpenCode.

From 1.1.4, a CLI pane in a room without a project of its own works in that room's own folder, `/workspaces/<room id>`, which is kept across updates and included in backups. Earlier releases started it in `/etc`, where the agent cannot create files, so a first request such as "create a page" failed. The last step of the Setup & connections wizard (Ready) also lists three first prompts with **Copy** buttons; paste one into the OpenCode pane and press Enter.

OpenCode is built into the SpaceApp CLI image (`opencode-ai` 1.18.4 in release 1.1.4). It needs no account and no API key for its free models, which are served by OpenCode Zen.

**The free starter model.** On its first launch, OpenCode chooses a working free model. From 1.1.2 on, it tries **Big Pickle** (`opencode/big-pickle`) first, and a model passes only if it completes a real tool call: it must read a small file with its read tool and answer with the random value inside it. If Big Pickle fails, the newest free models that support tool calls are tried in the same way. (1.1.1 accepted the first free model that answered a plain text request, which could pick a model that later failed on tool calls.)

The check can take up to about two minutes on first launch. The chosen model is shown under the prompt, for example `Build · Big Pickle OpenCode Zen`. In the 1.1.2 release tests, Linux, macOS and Windows all picked Big Pickle on the first attempt; free models change upstream, so yours can differ.

If no free model passes, OpenCode reports `No free OpenCode model completed a request. The app remains available; retry OpenCode later or choose a provider in Settings.`

![An OpenCode pane in SpaceApp, ready for a prompt, with the free model name under the input box](/docs-media/opencode-ready.webp "OpenCode ready for its first prompt in a 1.1.1 test install. The rooms in your dock will have your own names.")

Free models are offered by OpenCode Zen under OpenCode's own terms and privacy policy, which you should read before sending private code. They can be rate-limited, changed or withdrawn upstream; SpaceApp does not guarantee permanent free capacity.

## 9. Your first prompt

Click inside the OpenCode pane, type a prompt and press Enter. A good first prompt needs no project and makes the model use a tool, which is where weak models fail:

```text
List the files in your current directory, then explain in three short bullet points what rooms, panes and memory are in SpaceApp.
```

A working agent shows its tool call (the directory listing), then the answer, and finally a line with the model name and the elapsed time, such as `Build · <model> · 37.2s`. A first answer can take a minute or more on a free model.

Once you have [registered a project](#workspace-registration), give the agent a read-only task in it. Registered projects appear inside SpaceApp under `/workspaces/<folder-name>`:

```text
Look at the project in /workspaces/example. Tell me what it does and where its entry point is, with file paths as evidence. Do not change any files.
```

Then try one small, reviewable change, and inspect the diff yourself before you rely on it. A visible pane or a long answer is not proof that the work was done; check the files.

## 10. If the agent does not answer

Free models fail in ordinary ways: a provider is rate-limited or temporarily unavailable, or a model cannot continue after a tool call. Work through these steps in order:

1. **Give the first request time.** Model selection and the first answer can together take a couple of minutes.
2. **Stop the stuck request.** Press Esc in the OpenCode pane to interrupt it.
3. **Switch the model in OpenCode.** Type `/models`, pick another free OpenCode Zen model (Big Pickle, or one whose name ends in Free), and send the prompt again.
4. **Use your own provider.** Run `/connect` in OpenCode to add a provider account, or set up another CLI as described in [Providers & credentials](/docs/providers/).
5. **Check the host.** If no pane responds at all, run `doctor`, `status` and `logs` on the host and follow [Troubleshooting](/docs/troubleshooting/).

Since 1.1.2 the first-launch check accepts a free model only after it completes a real tool call, which removes the most common case (a model that answers plain text but fails on tools). A model can still stop working upstream later; then use step 3.

## 11. Workspace registration

No arbitrary host project is mounted by default. Register only directories agents may read or modify:

```bash
npx --yes run-spaceapp@latest workspace add /home/alice/code/example
npx --yes run-spaceapp@latest workspace add /Users/alice/code/example
npx --yes run-spaceapp@latest workspace add /absolute/path/to/reference --read-only
npx --yes run-spaceapp@latest workspace list
npx --yes run-spaceapp@latest workspace remove /absolute/path/to/reference
npx --yes run-spaceapp@latest up
```

The first two add examples illustrate different OS paths; use the one matching the host. On Windows Command Prompt:

```bat
npx --yes run-spaceapp@latest workspace add "C:\Users\Alice\code\example"
```

The path must be an existing directory given as an absolute path. `workspace add` prints `Workspace registered: <path>`, and the project appears inside SpaceApp as `/workspaces/<folder-name>`. `workspace list` prints the registered projects as JSON.

Apply changed mounts using `up`; service recreation can affect active work. Removal unregisters the project mount, not the source repository itself. Check actual runtime mounts if an agent cannot see a registered path.

Read-only access is appropriate for reference projects. Host-root access is a separate, much broader mode; selecting large does not grant it. Repository instructions and source files remain untrusted inputs even inside an authorized workspace.

## 12. Provider installation and credentials

OpenCode is built into the image. The other ten CLIs are not: each is downloaded into this installation's private provider volume the first time you use it, or ahead of time with `provider install`. Versions are pinned per SpaceApp release; this table shows launcher 1.1.1.

| Provider ID | CLI | Package in 1.1.1 | Installed | How to sign in |
| --- | --- | --- | --- | --- |
| `opencode` | OpenCode | `opencode-ai@1.18.4` | Built into the image | No sign-in for free models; `/connect` inside OpenCode for your own provider, or an API key |
| `codex` | Codex CLI | `@openai/codex@0.145.0` | On demand | Device-code login, or an API key |
| `claude` | Claude Code | `@anthropic-ai/claude-code@2.1.206` | On demand, from npm (never in the image) | Provider login, or an API key |
| `gemini` | Gemini CLI | `@google/gemini-cli@0.52.0` | On demand | Sign in inside the CLI, or an API key |
| `qwen` | Qwen Code | `@qwen-code/qwen-code@0.20.1` | On demand | Sign in inside the CLI, or an API key |
| `kimi` | Kimi Code | `@moonshot-ai/kimi-code@0.29.0` | On demand | Provider login, or an API key |
| `grok` | Grok Build | `@xai-official/grok@0.2.111` | On demand | Provider login, or an API key |
| `deepseek` | DeepSeek CLI (community, experimental) | `run-deepseek-cli@0.1.1` | On demand | API key only |
| `autohand` | Autohand Code | `autohand-cli@0.9.3` | On demand | API key only |
| `cursor` | Cursor Agent | Cursor's agent CLI archive, pinned build | On demand, from Cursor's download server | Provider login only |
| `copilot` | GitHub Copilot CLI | `@github/copilot@1.0.78` | On demand | Provider login only |

The SpaceApp application catalog recognizes 16 CLI identifiers, but the launcher's `provider` and `credentials` commands accept only the IDs above (`provider install` takes the ten besides OpenCode); do not assume the others work through these commands. Each provider's account, subscription, usage limits and terms are separate from SpaceApp.

### Install a CLI ahead of time

Each optional CLI downloads the first time you open it. To install one in advance, so the first pane starts without that wait:

```bash
npx --yes run-spaceapp@latest provider install codex
npx --yes run-spaceapp@latest provider install claude
```

Claude Code is never included in the published images, because its package does not come with a license that lets SpaceApp redistribute it. Opening a Claude Code pane for the first time, or running `provider install claude`, downloads the reviewed version from npm as your own action, and its use is subject to Anthropic's terms.

### Sign in with the provider's own flow

This is the preferred way. In SpaceApp, open **Setup & connections** (Help → Setup wizard), go to **Tools**, select **Show all tools**, and use the login action next to the CLI. It opens that CLI's official login, device-code or OAuth flow in a protected terminal. Connect one provider at a time and confirm it reports ready before adding the next.

### Or store an API key

For the providers that accept a key, the launcher reads it with masked input:

```bash
npx --yes run-spaceapp@latest credentials set gemini
```

The launcher prompts `Enter gemini credential:` and reads the value without echoing it; keys are never accepted as command-line arguments. It writes the key to `secrets/providers/gemini.key` in the installation root with owner-only permissions, recreates the CLI service so the key is imported, and prints `Credential stored and applied for gemini.` The CLI receives it as its usual environment variable (for example `GEMINI_API_KEY`, `OPENAI_API_KEY` for Codex, `ANTHROPIC_API_KEY` for Claude Code). Cursor and Copilot do not read an imported key; use their login.

```bash
npx --yes run-spaceapp@latest credentials list
npx --yes run-spaceapp@latest credentials remove gemini
```

In 1.1.1, `credentials list` prints the provider IDs the launcher accepts, grouped as `bundled`, `ownerInstalled` and `experimental`; it does not show which keys are stored. `credentials remove` deletes the local key file and prints `Credential removed and applied for gemini.`; it does not revoke the key upstream, so revoke or rotate it in the provider account when necessary.

### Where credentials are kept

Never paste credentials into room chat, prompts, project files or canonical memory. Provider OAuth/device state lives in an isolated Docker volume; the core service does not mount raw provider-key files or the provider-state volume. Setting or removing a key recreates the CLI service, so finish or coordinate active sessions first. Portable backups intentionally do not carry provider credentials.

The public community DeepSeek CLI is experimental and not an official DeepSeek CLI. Other operator-configured DeepSeek/Harness/Reasonix environments can differ; do not infer their behavior from this adapter.

## 13. Complete command families

Prefix each command with `npx --yes run-spaceapp@latest`, or use the explicitly selected installed launcher version. Arguments shown in angle brackets are placeholders, not literal input.

| Command | Purpose and effect |
| --- | --- |
| `help` | Show command list and supported options; works before installation. |
| `init` | Create installation configuration, secrets and runtime files; does not replace the complete install workflow. |
| `install` | Initialize/check prerequisites, pull/start the selected runtime, verify readiness and setup, optionally open browser. Also the preferred upgrade entry point. |
| `reinstall` | Recreate installation/runtime setup while preserving existing data and credentials through the supported flow. |
| `repair` | Inspect and repair existing configuration/runtime files; requires change approval. |
| `repair --dry-run` | Inspect intended repair without applying it. |
| `doctor` | Read-only check of Node.js, configuration, resources and Docker; one PASS/FAIL line each. |
| `doctor --fix` | Run repair behavior for the existing installation; not merely read-only diagnosis. |
| `up` | Start/apply the configured Compose stack. |
| `down` | Stop/remove the running Compose stack while retaining persistent data; interrupts services. |
| `status` | Show service state and bindings. |
| `logs` | Print the last 200 log lines of each service. Do not invent an unsupported follow flag. |
| `open` | Open the configured application URL in the host browser. |
| `support-bundle` | Write a small diagnostic JSON file (versions, settings, readiness); see [Troubleshooting](/docs/troubleshooting/). |
| `update [version]` | Update runtime images through the launcher's version/update workflow. |
| `rollback` | Return to the recorded previous image/configuration version; not database reversal. |
| `backup` | Create a portable application backup with manifest/checksums. |
| `restore` | Restore the latest selected valid portable backup after explicit confirmation. |
| `factory-reset` | Safety-backup/reset workflow that removes application state; destructive. |
| `workspace add <path> [--read-only]` | Register an allowed host project mount. |
| `workspace list` | Print registered projects as JSON. |
| `workspace remove <id-or-path>` | Unregister a workspace. |
| `credentials set <provider>` | Read/import a provider key through masked input. |
| `credentials list` | Print the provider IDs the launcher accepts (bundled, owner-installed, experimental); it does not show which keys are stored. |
| `credentials remove <provider>` | Remove the local imported key; does not revoke upstream. |
| `provider install <provider>` | Owner-install a supported optional CLI. |
| `owner reset-password` | Reset owner password through masked local input. |
| `owner rotate-setup-token` | Refresh an expired/unclaimed setup token; refused after owner claim. |
| `uninstall` | Remove containers/network, retain configuration, data volumes, secrets and backups. |
| `uninstall --purge-data` | Remove runtime volumes after explicit destructive confirmation. |

Do not assume restore takes an arbitrary file/path argument: the verified launcher selects the latest valid backup. `backup` and `logs` also do not accept arbitrary flags simply because Docker underneath has them.

## 14. Installation and global options

Installation/reinstallation options include:

- `--profile auto|small|medium|large|light|standard`: choose service/resource profile.
- `--access isolated|host-root`: choose access policy where supported by platform/runtime.
- `--with-companions`: include supported optional companion services.
- `--no-open`: skip automatically opening a browser.
- `--keep-data`: explicit preservation intent on reinstall.

Global options shown by the verified launcher:

- `--plan`: print the planned action without executing the change.
- `--json`: structured output where that command supports it; not a guarantee for all output.
- `--log-file <file>`: append execution logs to a chosen file; review logs before sharing.
- `--local-images`: use preloaded images; missing images fail. Intended for controlled offline/lab workflows, not proof that AI inference is offline.
- `--non-interactive`: fail when required input is missing instead of prompting.
- `--answers <json|path>`: supply answers; automated changes require explicit `confirm:true`.

`support-bundle --out <path>` is handled by the verified implementation to select a JSON output path. Check the chosen version before relying on options absent from abbreviated help. The launcher's complete help text, generated from the published package, is at the end of the [CLI reference](/docs/cli/) page.

Profile/access flags select choices but do not bypass final confirmation. Preserve license, elevation, typed destructive-confirmation and other gates. A dry-run establishes the plan, not that an installation or repair succeeded.

## 15. Automation example

For an authorized unattended install, create a non-secret answers JSON file:

```json
{
  "confirm": true,
  "profile": "auto",
  "access": "isolated",
  "companions": false,
  "telemetry": false,
  "open": false
}
```

Then run:

```bash
npx --yes run-spaceapp@latest install --non-interactive --answers answers.json
```

A file avoids platform-specific shell quoting problems. In launcher 1.1.1, `"telemetry": false` keeps the first-install ping off; `SPACEAPP_TELEMETRY` in the invoking environment overrides the file in either direction. Do not add provider keys or passwords to the answers file. Missing prerequisite approvals, terms acceptance or OS interactions can still prevent unattended completion. Read exit status and readiness evidence; a non-interactive process launch is not acceptance.

Use a dedicated installation root for a disposable test, and keep the root consistent on every follow-up command. Never reset an important installation to create a test fixture.

## 16. Health and troubleshooting flow

Start on the host, in the same OS account that installed SpaceApp (and with the same `SPACEAPP_HOME`, if you set one):

```bash
npx --yes run-spaceapp@latest doctor
npx --yes run-spaceapp@latest status
npx --yes run-spaceapp@latest logs
```

`doctor` is read-only. It prints one line per check, `PASS` or `FAIL`, and exits with a non-zero status if anything failed:

| Check | What a `FAIL` means |
| --- | --- |
| `Node.js` | The Node.js running the launcher is older than 20. |
| `Configuration` | No installation in this root, or its configuration is invalid. The line names the problem. |
| `CPU`, `Memory`, `Free disk` | The host is below the installed profile's requirement. |
| `Docker CLI` | `docker` is not on the PATH (`not found on PATH`). |
| `Docker Compose` | The Compose plugin is missing. |
| `Docker Engine` | The CLI exists but the engine is stopped or this user cannot reach it (`installed but not running or inaccessible`). |

When Docker is missing, `doctor` adds a hint such as `Run "npx --yes run-spaceapp@latest install" to install and start Docker Engine and Compose automatically on supported Linux distributions.` When the engine is down it says `Open Docker Desktop, complete any first-run prompt, then run "npx --yes run-spaceapp@latest doctor" again.` (Windows and macOS) or `Start Docker Engine, verify the current user can access it, then run "npx --yes run-spaceapp@latest doctor" again.` (Linux).

`status` shows the containers (`docker compose ps`) and `logs` prints the last 200 log lines of each service; neither follows the log. Container state alone does not establish app readiness, owner authentication, provider login or successful agent work.

| Symptom | First useful action |
| --- | --- |
| npx not found | Install/verify Node.js and npm in this terminal; open a new terminal after installing Node.js. |
| PowerShell blocks npx.ps1 | Use Command Prompt or `npx.cmd`. |
| Docker missing | Run `install`; it installs Docker on supported platforms. Otherwise install Docker Engine and Compose yourself. |
| Docker Desktop not ready after 10 minutes | Open Docker Desktop, finish its first-run prompts (on Windows select Skip on Welcome to Docker or sign in), restart Windows if asked, wait for the engine to run, then run `install` again. |
| Docker Engine stopped (Linux) | Run `install` again; it starts the service. Check that your user is in the `docker` group and that you logged in again after it was added. |
| Insufficient resources | Check host and Docker allocations against actual profile thresholds. |
| Services not ready after 10 minutes | Read the status and log output the install printed; run `doctor`, then `install` again. Your data volumes are kept. |
| App not reachable | Check status/logs and the configured host URL, not another device's localhost. |
| Setup token expired | Run `owner rotate-setup-token`; it works only while no owner exists. |
| Owner password lost | Use local owner password reset. |
| Agent does not answer | Switch the OpenCode model; see [Your first session](/docs/first-session/#if-the-agent-does-not-answer). |
| CLI visible but cannot work | Check installation, login, model availability, quota and project mounts separately. |
| Browser feature absent | Check profile includes managed browser and service is healthy. |
| Background delivery absent | Check worker profile, connector authentication and actual delivery evidence. |
| Workspace missing | Check OS user, SPACEAPP_HOME, registration and applied mounts. |
| Upgrade reports RECOVERY_REQUIRED | Preserve current state; inspect logs and repair attempted version before considering restore. |

Running `install` again on an installation of the same version does not reinstall. It asks what to do, with repair as the default:

```text
SpaceApp 1.1.1 is already installed. What would you like to do?
  [1] Run doctor diagnostics (read-only)
  [2] Repair the runtime (recreate containers from the current configuration)
  [3] Cancel
Select 1-3 [2]:
```

Do not fix ordinary install failures with factory reset, volume deletion, system-wide Docker pruning or a blind downgrade. Preserve active sessions and unrelated containers.

## 17. Example: diagnose, repair, verify

This is a real sequence from the 1.1.1 release tests. The same result appeared on Linux, macOS and Windows 11; the Linux run is shown, with the test's own paths replaced by a default installation root. To simulate a damaged installation, the test changed one setting in the configuration file to an invalid value.

**1. Diagnose.** `doctor` finds the problem and exits with status 1. The configuration could not be read, so the disk check uses the fresh-install threshold:

```text
$ npx --yes run-spaceapp@latest doctor
PASS Node.js: v22.23.1
FAIL Configuration: companionsEnabled must be boolean.. Run install for a new setup, or doctor --fix for an existing setup.
PASS CPU: 4 available; 4 required
PASS Memory: 7.7 GiB available; 7 GiB usable (8 GB-class system) required
PASS Free disk: 17.5 GiB available; 6.5 GiB required
PASS Docker CLI: available
PASS Docker Compose: available
PASS Docker Engine: available
```

**2. Repair.** `doctor --fix` shows a plan, waits for your approval, then recreates the containers from the repaired configuration without deleting data. Shortened: Docker's container lines are left out.

```text
$ npx --yes run-spaceapp@latest doctor --fix
SpaceApp setup plan:
  - Repair configuration and recreate the current runtime without deleting data.
  - companionsEnabled is the string "false" and will be converted to the boolean false.
Apply this plan? [y/N] y
PASS Free disk: 17.50 GiB available; 0.50 GiB required additionally for repair (images 0.00, checkpoint 0.00, reserve 0.5)
PASS Docker storage: 17.50 GiB available; 0.50 GiB required additionally
SpaceApp 1.1.1 runtime repaired.
```

**3. Verify.** Run `doctor` again; every check passes and the exit status is 0. The `Configuration` line now shows the installation root, and the disk check switches to the space needed for maintenance:

```text
$ npx --yes run-spaceapp@latest doctor
PASS Node.js: v22.23.1
PASS Configuration: /home/alice/.config/spaceapp
PASS CPU: 4 available; 4 required
PASS Memory: 7.7 GiB available; 7 GiB usable (8 GB-class system) required
PASS Free disk: 17.9 GiB available; 0.5 GiB required additionally for maintenance
PASS Docker CLI: available
PASS Docker Compose: available
PASS Docker Engine: available
```

In the test, workspaces, secrets and database contents were checked after the repair and were unchanged. A passing `doctor` proves the prerequisites and configuration; open the app and run a small agent task to prove the rest.

## 18. Repair and reinstall

```bash
npx --yes run-spaceapp@latest repair --dry-run
npx --yes run-spaceapp@latest repair
npx --yes run-spaceapp@latest doctor --fix
npx --yes run-spaceapp@latest reinstall --keep-data
```

Use one appropriate path after inspecting the diagnosis; the examples are alternatives, not an instruction to execute all of them. `repair` and `doctor --fix` run the same repair; `repair --dry-run` prints the planned configuration repairs as JSON without changing anything. Repair starts Docker if it is stopped, reconstructs supported configuration/runtime state and recreates containers. It is not a general promise to repair corrupted database contents or recover deleted project files.

Reinstall is a preservation-oriented setup operation, not factory reset; it keeps data by default. Still back up and coordinate service recreation. Verify retained owner access, workspaces, data, memory and provider readiness after any disruptive action.

## 19. Upgrades

Preferred sequence for an authorized update:

```bash
npx --yes run-spaceapp@latest backup
npx --yes run-spaceapp@latest doctor
npx --yes run-spaceapp@latest install
npx --yes run-spaceapp@latest status
```

The universal install resolves the current launcher/runtime, preserves profile unless changed, checks additional disk, pulls matching images and recreates the stack. Persistent data, secrets, credentials and registered projects are retained by the supported workflow.

Before cutover, the launcher pauses writers and verifies a checkpoint. If the new runtime fails readiness after cutover, it stops writers, retains current database/volumes and reports RECOVERY_REQUIRED. It does not silently restore an older database that could discard writes accepted by the new runtime.

From 1.1.4, SpaceApp tells you when a newer release exists: the top bar shows **Update available: vX**, which opens the update command (`npx --yes run-spaceapp@latest update`) with a **Copy** button and a link to the release notes. Run it on the machine where SpaceApp is installed; data, settings and workspaces are kept.

Investigate the attempted version, use `doctor --fix` where appropriate and preserve newer data before deciding on rollback or restore. Test release changes on an owned disposable environment when possible. A successful image pull is not a successful upgrade.

## 20. Backup contents and limitations

```bash
npx --yes run-spaceapp@latest backup
```

Portable backups are stored below the installation's backups directory. Documented contents:

- `database.dump`: PostgreSQL custom-format dump.
- `data.tar.gz`: application data, excluding separately handled memory and browser profiles.
- `memory.tar.gz`: mutable owner memory.
- `manifest.json`: format, sizes and SHA-256 checksums.

Excluded: provider API-key files, OAuth/device login state and provider-state volume, registered host workspace contents, and browser profiles. Keep separate project backups and provider recovery arrangements. A portable backup does not transfer every login to another host.

Backup files are owner-restricted but still sensitive. Protect them from public sharing and retain verified copies according to owner policy. A successful backup command is not a demonstrated restore; test recovery in a disposable environment with representative data.

## 21. Restore and rollback are different

Restore:

```bash
npx --yes run-spaceapp@latest restore
```

The verified flow requires typing RESTORE, selects the newest valid backup, creates a pre-restore backup, stops relevant services, validates integrity/archive paths, replaces data/memory/database and restarts. Restore replaces current application state and can discard newer changes. Preserve needed data and an offline backup copy first.

Rollback:

```bash
npx --yes run-spaceapp@latest rollback
```

Rollback returns to the single recorded prior image/configuration version. It does not reverse migrations or data-format changes. Verify backward compatibility and release recovery instructions. Do not automatically combine rollback with restore; that is a separate destructive decision.

When moving to a new host, reconnect provider accounts and register local project paths. Validate owner login, memory, files, workspaces and real agent execution after recovery.

## 22. Reset and removal

`factory-reset` is for an explicitly requested fresh state, not routine diagnosis:

```bash
npx --yes run-spaceapp@latest factory-reset
```

The workflow attempts a safety backup and requires typed FACTORY-RESET confirmation before destructive reset. In the reviewed implementation a backup problem can be reported without preventing the reset confirmation; independently verify a usable backup before proceeding. A safety backup does not cover excluded provider credentials or host projects. Read the displayed scope and stop if it does not match the intended installation.

Ordinary removal:

```bash
npx --yes run-spaceapp@latest uninstall
```

This removes containers/network while retaining data volumes, configuration, secrets and backups. It does not remove the optional global npm launcher. If appropriate after runtime removal:

```bash
npm uninstall -g run-spaceapp
```

Destructive volume removal:

```bash
npx --yes run-spaceapp@latest uninstall --purge-data
```

This removes application/database/memory/provider/workspace-volume state after confirmation. Host files under the installation root, including backups and provider key files, can remain; do not describe it as secure erasure of every file or deletion of registered host repositories. Review leftovers deliberately and never delete unrelated Docker resources.

## 23. Access and remote use

New installations default to isolated access with explicitly registered workspaces. Host-root mode is Linux-only where supported by the matching launcher/runtime and intentionally exposes the host filesystem, including a writable host root to CLI processes.

It is not necessary for ordinary project work and is not automatically selected by a hardware profile. It can permit reading credentials and modifying operating-system files. Only use it as an explicit owner decision; do not recommend it as a generic permission repair.

Default loopback binding limits direct network access. Remote clients need a properly configured reachable address, TLS/access policy and firewall. Use release-specific configuration instructions. Do not invent `--host` flags or expose the instance broadly as a shortcut.

## 24. Telemetry and outbound traffic

Telemetry is off unless you turn it on. The install wizard asks `Enable anonymous usage telemetry? [y/N]`, and the default is No. Only when you answer Yes does a successful first install (not an upgrade or re-run) send one ping to the public SpaceApp site. The payload contains a random install ID, OS, architecture, launcher/runtime versions and installation date, not project files or credentials.

This is the behavior of launcher 1.1.1. Earlier launchers (1.1.0 and older) sent the ping unless `SPACEAPP_TELEMETRY` disabled it, whatever the wizard answer.

From 1.1.4, an installation with telemetry turned on also sends **one** event the first time an agent finishes an answer, so the project can see how many new installations reach a working agent. It contains the event name (`first_answer`), the SpaceApp version, the CPU architecture, the date and a new random ID that is not linked to the install ping or to anything in the installation. No prompt, answer, model, account, file or path is sent. It is sent once per installation (a marker in the data volume records it) and never when telemetry is off.

The environment variable `SPACEAPP_TELEMETRY` overrides the answer: `0`, `false`, `no` or `off` never send the ping; `1`, `true`, `yes` or `on` send it, which is how unattended installs opt in. To be explicit about opting out in your shell:

```bash
SPACEAPP_TELEMETRY=0 npx --yes run-spaceapp@latest install
```

```bat
set SPACEAPP_TELEMETRY=0
npx --yes run-spaceapp@latest install
```

```powershell
$env:SPACEAPP_TELEMETRY = "0"
npx.cmd --yes run-spaceapp@latest install
```

Use the example for your shell. This controls the installer ping, not registry downloads, configured provider requests or connected integrations. Do not claim that self-hosted means no data ever leaves the machine.

## 25. Support bundles and useful bug reports

```bash
npx --yes run-spaceapp@latest support-bundle
```

The command writes one JSON file and prints `SpaceApp support bundle generated: <path>`. By default the file is `support-bundle-<UTC timestamp>.json` in the installation root, readable only by your user; `--out <path>` writes it elsewhere. In launcher 1.1.1 it contains:

- `system`: OS platform, CPU architecture and Node.js version;
- `launcher`: launcher and runtime versions;
- `installation`: the installation root path and the non-secret settings (installed version, profile, access mode, companions on/off, bind address, port and previous version);
- `health`: the HTTP status of the app's `/readyz` check, or the error if it could not be reached.

It does not include passwords, setup tokens, API keys, provider logins, session secrets, database contents, workspace files or logs. It does include the installation root path, which usually contains your OS user name; edit that before posting it publicly. Because the bundle has no logs, attach the relevant part of `status` and `logs` output as well, after reading it for anything private.

Useful reports include OS/architecture, launcher/runtime version, profile, exact non-secret command, expected/observed result, exit status and relevant bounded logs. Exclude passwords, setup tokens, API keys, cookies, OAuth state, unrelated private files and private browser profiles.

Public issue: https://github.com/oll4com/spaceapp/issues
Security report: follow https://github.com/oll4com/spaceapp/blob/main/SECURITY.md

## 26. Release and evidence checklist

Before declaring installation/update/recovery complete, verify the intended OS user/root, selected runtime version/profile, healthy relevant services, application readiness, owner access, retained workspace/memory/data, provider readiness and an actual small agent task. Keep active user sessions and unrelated work safe.

Public npm launcher, container images, source main, release tags and native client builds are distinct artifacts. A newer source candidate or green CI job does not prove that npm latest or downloadable assets match it. Use official release metadata and actual installed versions.

These documents are documentation deliverables, not a new application release. For operational details always prefer the chosen release's help/source over stale examples.

## 27. Official references

- https://www.npmjs.com/package/run-spaceapp
- https://github.com/oll4com/spaceapp/releases
- https://github.com/oll4com/spaceapp/blob/main/docs/getting-started.md
- https://github.com/oll4com/spaceapp/blob/main/docs/cli-providers.md
- https://github.com/oll4com/spaceapp/blob/main/docs/operations.md
- https://github.com/oll4com/spaceapp/blob/main/docs/security-model.md
- https://github.com/oll4com/spaceapp/tree/main/packages/run-spaceapp