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):
npx --yes run-spaceapp@latest doctor
npx --yes run-spaceapp@latest status
npx --yes run-spaceapp@latest logsdoctor 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. |
| 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:
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.
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:
$ 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: available2. 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.
$ 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:
$ 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: availableIn 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.
Repair and reinstall#
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-dataUse 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.
Support bundles and useful bug reports#
npx --yes run-spaceapp@latest support-bundleThe 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/readyzcheck, 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