spaces-startos/README.md

Spaces on StartOS

Upstream docs: https://docs.spacesprotocol.org/

Everything not listed in this document should behave the same as upstream spaced / space-cli. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

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.

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Actions
• Backups and Restore
• Health Checks
• Limitations and Differences
• What Is Unchanged from Upstream
• Quick Reference for AI Consumers

---

Image and Container Runtime

Field	Value
Image	docker.io/horologger/spaces
Architectures	linux/amd64, linux/arm64
Entrypoint	StartOS-managed (image entrypoint is not used)

The image bundles spaced, space-cli, bitcoin-cli, gotty, node, npm, screen, and a small shell environment. StartOS ignores the image's docker_entrypoint.sh; daemons are defined in startos/main.ts.

Volume and Data Layout

Path	Volume	Purpose
/data	main	Spaces data directory (SPACED_DATA_DIR), wallets, indexes, and store.json
/data/mainnet/.cookie	main	Spaced RPC cookie (auto-generated by spaced at startup)
/data/store.json	main	StartOS-managed credentials (web-UI password + bitcoind RPC user/password)

Installation and First-Run Flow

On the first install, StartOS:

1. Seeds store.json.password with a random 32-char alphanumeric admin password and creates a critical task that points the user at Show Web UI Credentials so the password can be copied before login.
2. Seeds store.json.btcAuth with a random spaces:<random> RPC credential pair and creates a critical cross-service task on Bitcoin that runs bitcoind's generate-rpc-dependent action to register the credentials in bitcoin.conf.
3. Launches spaced as a managed daemon (no screen, no shell auto-start).
4. Launches the gotty web terminal once spaced is up.

The user is not prompted to choose a chain or RPC mode -- this package is mainnet-only.

Configuration Management

StartOS-Managed	Upstream-Managed
Web-UI username / password (admin + generated password)	spaced runtime tuning via SPACED_* env vars in the image
Bitcoin RPC username / password (registered on bitcoind)	Wallet creation, bidding, and registration -- all driven via space-cli inside the terminal
Chain selection (locked to mainnet)	space-cli flags and subcommands
Spaced data directory and RPC bind

Network Access and Interfaces

Interface	Port	Protocol	Exposure	Notes
Web UI (gotty terminal)	8080	HTTP	LAN / .local / Tor / clearnet (via StartOS)	Basic auth: admin:<store.password>
Spaced RPC	7225	HTTP JSON-RPC	Loopback only	Internal use, cookie-authenticated

Actions

ID	Name	Visibility	Availability	Purpose
reset-password	Reset Web UI Password	Enabled	Any	Regenerates the web-UI password and restarts the terminal daemon
show-credentials	Show Web UI Credentials	Hidden	Any	Surfaces the current admin username + masked password (launched by the first-install task)
set-bitcoin-rpc	Set up Bitcoin RPC	Enabled	Any	Re-invokes bitcoind's generate-rpc-dependent with the stored credentials. Safe to call repeatedly.
sync-status	Sync Status	Enabled	Only running	Runs space-cli getserverinfo inside the daemon container and returns the JSON output
reset-spaced-state	Reset Spaced State	Enabled	Any	Deletes /data/mainnet/ so spaced resyncs its index from spaces' anchor. Preserves store.json (passwords + RPC credentials). Use when spaced crash-loops on a stale or corrupt index.

Backups and Restore

sdk.Backups.ofVolumes('main') -- the entire /data volume is backed up, including spaced state, wallets, the block index, and store.json. On restore, the same idempotent init logic runs and reuses the existing credentials in store.json.

Health Checks

ID	Display	Grace period	Behaviour
spaced (daemon ready)	Spaced RPC	120 s	TCP listen on 127.0.0.1:7225
web-terminal (daemon ready)	Web Interface	default	TCP listen on 0.0.0.0:8080
sync (standalone)	Spaced Sync	300 s	Exec space-cli getserverinfo; reports success when ready=true, otherwise loading with progress percentage

Limitations and Differences

1. Mainnet only. Testnet, testnet4, signet, and regtest are not exposed.
2. The image's docker_entrypoint.sh is not used. Its auto-start of spaced inside screen would conflict with the StartOS-managed daemon.
3. Web UI is a terminal, not a graphical app. All Spaces operations happen via space-cli (aliased as spaces inside the shell).
4. Only port 8080 (gotty) is exposed. Spaced RPC, and any other ports present in the image (e.g. 22253, 3000, 5173, 8081) are not bound.
5. Bitcoin Core 31.x is the only supported dependency. Earlier majors are not allowed by the manifest version range.
6. The web terminal is independent of spaced. Gotty stays reachable even when spaced is crash-looping, so you can always shell in to diagnose.

What Is Unchanged from Upstream

• space-cli subcommands and flags work exactly as documented upstream.
• spaced honours all SPACED_* environment variables not otherwise set by StartOS.
• Wallet files, the spaces database, and the block index are managed by spaced itself; StartOS only provides the volume.
• bitcoind connectivity follows the standard StartOS dependency-service model (bitcoind.startos:8332).

Using the Web Terminal

After install:

1. Run the Show Web UI Credentials action (the install task surfaces it).
2. Open the Web UI from the StartOS dashboard.
3. Log in with admin and the displayed password.
4. Use spaces <subcommand> -- it expands to space-cli --chain mainnet --rpc-cookie /data/mainnet/.cookie <subcommand>.

Examples:

spaces getserverinfo
spaces walletcreate default
spaces walletbalance default

Quick Reference for AI Consumers

package_id: spaces
upstream_version: subspacesplus
image: docker.io/horologger/spaces:v0.0.9s
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports:
  ui: 8080
  spaced_rpc: 7225  # loopback only
dependencies:
  - bitcoind
startos_managed_env_vars:
  - SPACED_CHAIN
  - SPACED_DATA_DIR
  - SPACED_RPC_BIND
  - SPACED_RPC_PORT
  - SPACED_RPC_URL
  - SPACED_BLOCK_INDEX
  - SPACED_BITCOIN_RPC_URL
  - SPACED_BITCOIN_RPC_USER
  - SPACED_BITCOIN_RPC_PASSWORD
  - BTC_RPC_HOST
  - BTC_RPC_PORT
  - BTC_RPC_USER
  - BTC_RPC_PASSWORD
  - APP_USER
  - APP_PASSWORD
actions:
  - reset-password
  - show-credentials
  - set-bitcoin-rpc
  - sync-status
  - reset-spaced-state