spaces-startos/instructions.md

Spaces

Spaces is a permissionless protocol for sovereign Bitcoin-anchored identities. This package runs the spaced daemon against Bitcoin mainnet and exposes space-cli through a browser-based terminal.

Getting set up

On first install, StartOS will:

1. Prompt you with a critical task — Show Web UI Credentials — to copy the admin username and the auto-generated password for the web terminal.
2. Prompt you with a second critical task on Bitcoin to run generate-rpc-dependent and register Spaces' RPC user in bitcoin.conf. Approve the form (it is pre-filled) and Bitcoin will restart with the new credentials.

Once both tasks are complete:

1. Open the Web UI from Spaces' dashboard.
2. Log in with admin and the displayed password.
3. Inside the terminal, run spaces getserverinfo to confirm that spaced is talking to Bitcoin and has begun indexing.

Using space-cli

Inside the web terminal, the spaces alias expands to space-cli --chain mainnet --rpc-cookie /data/mainnet/.cookie. So:

spaces getserverinfo
spaces walletcreate default
spaces walletbalance default

Actions

• Reset Web UI Password — rotates the admin password and restarts the terminal daemon.
• Show Web UI Credentials — surfaces the current admin password (hidden; reachable through the install task).
• Set up Bitcoin RPC — re-runs the bitcoind credential setup if state ever drifts. Safe to call repeatedly.
• Sync Status — runs space-cli getserverinfo against the local daemon and returns the JSON output.
• Reset Spaced State — wipes /data/mainnet/ so spaced resyncs its index from spaces' anchor. Use this if spaced is crash-looping on a stale or corrupt index. store.json (passwords + RPC credentials) is preserved.
• Export Wallet — runs space-cli exportwallet on the default wallet, writes the JSON to /data/mainnet/wallets_backup/default.json inside the container, and surfaces the same JSON as a copyable result so you can save it locally. Requires the service to be running.
• Import Wallet — paste a previously-exported default.json payload to restore it. The action rotates any existing /data/mainnet/wallets_backup/default.json and /data/mainnet/wallets/default to .bakNNN suffixes so no prior state is lost, then calls space-cli importwallet and space-cli loadwallet. Requires the service to be running.
• Create Registry API Keys — generates (or rotates) REGISTRY_API_KEY and SUBSD_API_KEY for the Subspaces registry. Required before the registry daemon will start.
• Show Registry API Keys — displays the stored registry keys.

Subspaces registry API keys

The embedded registry-server will not start without two distinct bearer secrets. Before enabling Subspaces (or when StartOS prompts you after):

1. Run Create Registry API Keys — generates REGISTRY_API_KEY and SUBSD_API_KEY (same shape as openssl rand -hex 32).
2. In the Subspaces Web UI, open Settings → Registry Server, set Auth Token to SUBSD_API_KEY, and click Test.
3. Give REGISTRY_API_KEY to any intake client that calls POST /register.

Use Show Registry API Keys to retrieve the stored values later, or re-run Create Registry API Keys to rotate them (then update the Auth Token).

Limitations

• Mainnet only. No testnet, signet, or regtest.
• Container images (see also the package manifest): the spaced runtime uses horologger/spaces:v0.3.0; Subspaces, Certrelay, and Nacho use horologger/subs:v0.1.2c, horologger/certrelay:v0.2.8, and horologger/nacho:v1.0.0b.
• The image's docker_entrypoint.sh is not used. spaced is managed by StartOS, not started inside a screen session by login.
• The only externally bound port is 8080 (gotty). Spaced RPC stays on loopback.

Links

• Project home: https://spacesprotocol.org
• Upstream docs: https://docs.spacesprotocol.org/
• Source: https://github.com/spacesops/spaced
• Package source: https://github.com/horologger/spaces-startos