spaces-startos/README.md

<p align="center">
  <img src="icon.png" alt="Spaces" width="180" />
</p>

# 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`](https://github.com/spacesops/spaced) daemon
against Bitcoin **mainnet** and exposes [`space-cli`](https://github.com/spacesops/spaced)
through a browser-based terminal.

---

## Table of Contents

- [Image and Container Runtime](#image-and-container-runtime)
- [Volume and Data Layout](#volume-and-data-layout)
- [Installation and First-Run Flow](#installation-and-first-run-flow)
- [Configuration Management](#configuration-management)
- [Network Access and Interfaces](#network-access-and-interfaces)
- [Actions](#actions)
- [Backups and Restore](#backups-and-restore)
- [Health Checks](#health-checks)
- [Limitations and Differences](#limitations-and-differences)
- [What Is Unchanged from Upstream](#what-is-unchanged-from-upstream)
- [Quick Reference for AI Consumers](#quick-reference-for-ai-consumers)

---

## Image and Container Runtime

| Field | Value |
| --- | --- |
| Spaces image | `docker.io/horologger/spaces:v0.3.0` |
| Subspaces image | `docker.io/horologger/subs:v0.1.2c` |
| Certrelay image | `docker.io/horologger/certrelay:v0.2.8` |
| Nacho image | `docker.io/horologger/nacho:v1.0.0b` |
| Architectures | `linux/amd64`, `linux/arm64` |
| Entrypoint | StartOS-managed (image entrypoints are **not** used directly) |

The Spaces image bundles `spaced`, `space-cli`, `bitcoin-cli`, `gotty`, `node`,
`npm`, `screen`, and a small shell environment. StartOS ignores the Spaces
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 (Space-CLI Web UI password, bitcoind RPC user/password, spaced RPC user/password, registry API keys) and feature config (Subspaces toggles, Certrelay + Nacho settings). |
| `/data/subspaces/data` | `main` | `subs` runtime data (`SUBS_DATA_DIR`) — handles, proofs, config.db. Persists across restarts and enable/disable toggles. |
| `/data/subspaces/prover` | `main` | Working directory for the `subs-prover` daemon. |
| `/data/subspaces/registry` | `main` | Working directory for the `registry-server` daemon. |
| `/data/certrelay/data` | `main` | Certrelay data directory (`CERTRELAY_DATA_DIR`) — anchors, peer state, sqlite. |
| `/data/bin/fabric` | `main` | The `fabric` CLI, copied from the certrelay image on each start so the gotty terminal (which has `/data/bin` on PATH) can resolve handles. |
| `/data/bin/monitor` | `main` | The `monitor` CLI, copied from the certrelay image on each start (file only — not run as a daemon). |
| `/data/support.pdf` | `main` | Workshop PDF served by nacho. Uploaded/replaced via the **Upload Support PDF** action. Missing until an upload has been performed. |
| `/data/nacho/ignore_names.txt` | `main` | Comma-separated names hidden from the nacho UI (read at runtime). Created by the `nacho-setup` oneshot with the default (`fold,swifty`) on first start; managed by the **Configure Nacho** action. |

## 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 Space-CLI 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. Seeds `store.json.spacedAuth` with a random `spaces:<random>` credential
   pair. Spaced is configured to require these via `SPACED_RPC_USER` /
   `SPACED_RPC_PASSWORD` (cookie auth is **not** used in this package), so the
   gotty terminal's `spaces` alias and other clients share a single auth path.
4. Seeds `store.json` certrelay defaults: `certrelaySelfUrl =
   https://certrelay.spacesops.com`, `certrelayBootstrap = false`,
   `certrelayHealthcheckHandle = account-digital-useful.genesis@key`.
5. Seeds `store.json` nacho defaults (`nachoWorkshopPdfLinkText = ''`) and
   `store.json.enableSubspaces = false`, `store.json.enableSubsProver = false`.
   The nacho ignore-names list lives in `/data/nacho/ignore_names.txt` (not
   in the store); the `nacho-setup` oneshot creates that file with the
   default (`fold,swifty`) on first daemon start if it doesn't exist.
   Registry API keys (`registryApiKey` / `subsdApiKey`) are **not** seeded at
   install — run **Create Registry API Keys** before (or when prompted after)
   enabling Subspaces; `registry-server` will not start without them.
6. Launches `spaced` as a managed daemon (no `screen`, no shell auto-start)
   and the `gotty` web terminal once the bashrc oneshot completes.
7. Runs `certrelay-setup` (creates `/data/certrelay/data`, copies `fabric` and
   `monitor` into `/data/bin/` as CLI files only) and launches the **certrelay**
   daemon on 7778.
   Certrelay is **always on**; its `CERTRELAY_SPACED_RPC_URL` uses the local
   spaced credentials from `store.spacedAuth`. Configure its self URL etc. via
   the **Configure Certrelay** action.
8. Runs `nacho-setup` (mkdir `/data/nacho`; seeds `ignore_names.txt` with the
   default `fold,swifty` if missing) and launches the **nacho** Expo daemon
   on 8082. Always on.

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 |
| Spaced RPC username / password (`SPACED_RPC_USER`/`SPACED_RPC_PASSWORD`) | `space-cli` flags and subcommands |
| Subspaces auth toggle + credentials (`SUBS_BASIC_AUTH_USER`/`SUBS_BASIC_AUTH_PASSWORD`, off by default) |  |
| Subspaces Prover auth toggle + credentials (`SUBS_PROVER_BASIC_AUTH_USER`/`SUBS_PROVER_BASIC_AUTH_PASSWORD`, off by default) |  |
| Chain selection (locked to `mainnet`) |  |
| Spaced data directory and RPC bind |  |

## Network Access and Interfaces

| Interface | Port | Protocol | Exposure | Notes |
| --- | --- | --- | --- | --- |
| Space-CLI Web UI (gotty terminal) | 8080 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | Basic auth: `admin:<store.password>` |
| Subspaces Web UI | 7777 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | `subs` daemon (subsd). Optional HTTP basic auth — off by default, gated by **Enable Subspaces Auth**. When on, both this UI and the Subs API are walled behind `SUBS_BASIC_AUTH_USER` / `SUBS_BASIC_AUTH_PASSWORD`. Only useful while Subspaces is enabled. |
| Subs API | 7777 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | The subsd REST API (same daemon/port as above), exposed as a distinct `api` interface separate from the prover and registry. Shares the optional Subspaces Auth wall with the Web UI (same port, same process). Only useful while Subspaces is enabled. |
| Subspaces Prover | 8888 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | `subs-prover` RISC Zero prover server (no GPU). Its own StartOS interface. Optional HTTP basic auth — off by default, gated by **Enable Subspaces Prover Auth**. When on, `SUBS_PROVER_BASIC_AUTH_USER`/`SUBS_PROVER_BASIC_AUTH_PASSWORD` are enforced. Only useful while Subspaces (and the prover toggle) is enabled. |
| Subspaces Registry | 8081 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | `registry-server` for publishing/resolving handles (remapped from its upstream default 8080 to avoid colliding with the gotty terminal on 8080). Its own StartOS interface. Only useful while Subspaces is enabled. |
| Certrelay | 7778 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | `certrelay` server (always on). Serves cryptographic proofs binding handles to owner keys. **Setup:** run **Configure Certrelay** and set `CERTRELAY_SELF_URL` to the publicly visible URL StartOS exposes for this interface. |
| Nacho | 8082 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | nacho Expo dev server (always on). The ignore list is read at runtime from `/data/nacho/ignore_names.txt` (managed by **Configure Nacho**). `EXPO_PUBLIC_API_BASE_URL` is derived dynamically from the Subs API StartOS interface (walked off its host: `sdk.host.getOwn(effects, 'subspaces-multi', h => h?.bindings[7777]?.interfaces['subs-api']).const()`), preferring the `.local` URL. Falls back to `http://127.0.0.1:7777` only if no address info is available. |
| Spaces API (spaced RPC) | 7225 | HTTP JSON-RPC | LAN / `.local` / Tor / clearnet (via StartOS) | spaced JSON-RPC, bound to `0.0.0.0` and exposed as the **Spaces API** interface. Static-cred-authenticated via `SPACED_RPC_USER` / `SPACED_RPC_PASSWORD` from `store.json.spacedAuth`. Internal clients still connect over loopback. |

## Actions

| ID | Name | Visibility | Availability | Purpose |
| --- | --- | --- | --- | --- |
| `reset-password` | Reset Space-CLI Web UI Password | Enabled | Any | Regenerates the Space-CLI Web UI password and restarts the terminal daemon |
| `show-credentials` | Show Space-CLI Web UI Credentials | Hidden | Any | Surfaces the current `admin` username + masked password (launched by the first-install task) |
| `show-password` | Show Space-CLI Web UI Password | Enabled | Any | Same as `show-credentials` but visible in the actions list, for routine re-display of the current admin credentials |
| `set-bitcoin-rpc` | Set up Bitcoin RPC | Enabled | Any | Re-invokes bitcoind's `generate-rpc-dependent` with the stored credentials. Safe to call repeatedly. |
| `show-spaced-credentials` | Show Spaces API Credentials | Enabled | Any | Surfaces the spaced RPC `SPACED_RPC_USER` / `SPACED_RPC_PASSWORD` (from `store.spacedAuth`) plus a loopback connection URL (password masked, all copyable). |
| `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. |
| `export-wallet` | Export Wallet | Enabled | Only running | Runs `space-cli exportwallet /data/mainnet/wallets_backup/default.json` and surfaces the resulting JSON as a masked/copyable result. The file is also persisted inside the volume at that path. |
| `import-wallet` | Import Wallet | Enabled | Only running | Accepts a pasted JSON payload (textarea), writes it to `/data/mainnet/wallets_backup/default.json` (rotating the existing file to `.bakNNN`), rotates `/data/mainnet/wallets/default` to `.bakNNN`, then runs `space-cli importwallet` + `loadwallet`. |
| `enable-subspaces` | Enable Subspaces | Enabled (hidden when already on) | Any | Sets `store.enableSubspaces = true` and triggers a service restart so the Subspaces chain (build → wallet → subs-prover → subs) takes effect. |
| `disable-subspaces` | Disable Subspaces | Enabled (hidden when already off) | Any | Sets `store.enableSubspaces = false` and triggers a service restart so the subs and subs-prover daemons stop. On-disk data at `/data/subspaces` is preserved. |
| `reset-subspaces-state` | Reset Subspaces State | Enabled | Any | Deletes `/data/subspaces` (runtime data only — binaries ship in the image). Use to wipe local handles/proofs. The spaces wallet on spaced is preserved. Warning-gated. |
| `set-subs-prover` | Enable / Disable Subspaces Prover | Enabled | Any | Toggle (`store.enableSubsProver`, default **off**) that starts/stops only the `subs-prover` daemon, independent of the overall Subspaces toggle. When off, the daemon doesn't start but its interface (8888) stays registered. Saving restarts the service. |
| `enable-subs-auth` | Enable Subspaces Auth | Enabled (hidden when already on) | Any | Sets `store.subsAuthEnabled = true`. If no credentials exist yet, generates `{ username: 'spaces', password: random32 }` and stores them in `store.subsAuth`. Restart re-launches `subs` with `SUBS_BASIC_AUTH_USER`/`SUBS_BASIC_AUTH_PASSWORD` env vars set. |
| `disable-subs-auth` | Disable Subspaces Auth | Enabled (hidden when already off) | Any | Sets `store.subsAuthEnabled = false`. Stored credentials are preserved so a later re-enable does not regenerate them. Restart re-launches `subs` without the auth env vars. |
| `show-subs-credentials` | Show Subspaces Auth Credentials | Enabled | Any | Surfaces the current `SUBS_BASIC_AUTH_USER`/`SUBS_BASIC_AUTH_PASSWORD` (from `store.subsAuth`) plus a loopback connection URL. Reports whether auth is currently enforced. |
| `set-subs-credentials` | Set Subspaces Auth Credentials | Enabled | Any | Set or rotate `store.subsAuth` and enable auth (`store.subsAuthEnabled = true`). Username is prefilled with the current value; password field is blank — leave it blank to auto-generate a random 32-char password, or paste your own. Restarts the service so subs picks up `SUBS_BASIC_AUTH_USER`/`SUBS_BASIC_AUTH_PASSWORD`. |
| `enable-subs-prover-auth` | Enable Subspaces Prover Auth | Enabled (hidden when already on) | Any | Sets `store.subsProverAuthEnabled = true`. If no credentials exist yet, generates `{ username: 'spaces', password: random32 }` and stores them in `store.subsProverAuth`. Restart re-launches `subs-prover` with `SUBS_PROVER_BASIC_AUTH_USER`/`SUBS_PROVER_BASIC_AUTH_PASSWORD` env vars set. |
| `disable-subs-prover-auth` | Disable Subspaces Prover Auth | Enabled (hidden when already off) | Any | Sets `store.subsProverAuthEnabled = false`. Stored credentials are preserved. Restart re-launches `subs-prover` without the auth env vars. |
| `show-subs-prover-credentials` | Show Subspaces Prover Auth Credentials | Enabled | Any | Surfaces the current `SUBS_PROVER_BASIC_AUTH_USER`/`SUBS_PROVER_BASIC_AUTH_PASSWORD` (from `store.subsProverAuth`) plus a loopback connection URL. Reports whether auth is currently enforced. |
| `set-subs-prover-credentials` | Set Subspaces Prover Auth Credentials | Enabled | Any | Set or rotate `store.subsProverAuth`. Same UX as `set-subs-credentials` (blank password → auto-generated). Restarts the service only if prover auth is currently enabled. |
| `create-registry-api-keys` | Create Registry API Keys | Enabled | Any | Generates (or rotates) `store.registryApiKey` + `store.subsdApiKey` as 64-char hex (`openssl rand -hex 32`). Both are required and must differ. Injected as `REGISTRY_API_KEY` / `SUBSD_API_KEY` into `registry-server`. Put `SUBSD_API_KEY` in subs Settings → Registry Server → Auth Token. Restarts so the registry picks up the new keys. When Subspaces is enabled without valid keys, a critical task points here. |
| `show-registry-api-keys` | Show Registry API Keys | Enabled | Any | Surfaces the stored `REGISTRY_API_KEY` and `SUBSD_API_KEY`. Returns blanks until Create Registry API Keys has been run. |
| `configure-certrelay` | Configure Certrelay | Enabled | Any | Sets `CERTRELAY_SELF_URL` (text), `CERTRELAY_BOOTSTRAP` (toggle), and `CERTRELAY_HEALTHCHECK_HANDLE` (text) in `store.json`; prefilled with current values. Saving restarts the service so certrelay picks up the new config. |
| `configure-nacho` | Configure Nacho | Enabled | Any | Writes the Ignore Names list to `/data/nacho/ignore_names.txt` (read at runtime by nacho — survives daemon restarts independent of the store) and sets `EXPO_PUBLIC_WORKSHOP_PDF_LINK_TEXT` in `store.json`. Prefill reads the file (with the package default as fallback) plus the current store value. Saving restarts the service. |
| `upload-support-pdf` | Upload Support PDF | Enabled | Any | Required `.pdf` file upload that overwrites `/data/support.pdf` on the main volume (read with `fs/promises`, piped via stdin into a temp `spaces` subcontainer's `cat > /data/support.pdf`). Split out from Configure Nacho because StartOS's form serializes an unselected `Value.file` as `{}` rather than `null`, which `Value.file(..., required: false).nullable()` rejects; a `required: true` dedicated action avoids the empty-form path entirely. |

## 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 `0.0.0.0:7225` (exposed as the Spaces API interface) |
| `subs-prover` (daemon `ready`) | Subspaces Prover | 60 s | TCP listen on `0.0.0.0:8888`. Only present when Subspaces **and** the `set-subs-prover` toggle are enabled (toggle defaults off). Polled every 30 s; nothing depends on it. |
| `subs-registry` (daemon `ready`) | Subspaces Registry | 60 s | TCP listen on `0.0.0.0:8081`. Only present when Subspaces is enabled. |
| `subs` (daemon `ready`) | Subspaces Web UI | 60 s | TCP listen on `0.0.0.0:7777`. Only present when Subspaces is enabled. |
| `certrelay` (daemon `ready`) | Certrelay | 120 s | TCP listen on `0.0.0.0:7778`. Always on. Polled every 30 s. |
| `nacho` (daemon `ready`) | Nacho | 120 s | TCP listen on `0.0.0.0:8082`. Always on. Polled every 30 s. |
| `web-terminal` (daemon `ready`) | Web Interface | default | TCP listen on `0.0.0.0:8080` |
| `sync` (standalone) | Spaced Sync | 30 s | Exec `space-cli --output-format json getserverinfo`; reports `success` when `ready=true && progress=100%`, otherwise `loading` with progress percentage |

## Limitations and Differences

1. **Mainnet only.** Testnet, testnet4, signet, and regtest are not exposed.
2. **The Spaces image's `docker_entrypoint.sh` is not used.** Its auto-start of
   `spaced` inside `screen` would conflict with the StartOS-managed daemon.
3. **Space-CLI Web UI is a terminal, not a graphical app.** All Spaces operations happen
   via `space-cli` (aliased as `spaces` inside the shell).
4. **Externally exposed ports** (each a StartOS interface): 8080 (gotty
   Space-CLI Web UI, always on), 7225 (Spaces API / spaced RPC, always on),
   7778 (Certrelay, always on), 8082 (Nacho, always on), and — only while
   Subspaces is enabled — 7777 (Subspaces Web UI + Subs API), 8888 (Subspaces
   Prover, only if its sub-toggle is on), 8081 (Subspaces Registry). The
   spaced RPC is authenticated (static creds). The Subspaces registry is
   remapped from its upstream default 8080 to 8081 to avoid colliding with the
   gotty terminal.
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.
7. **Subspaces is opt-in.** Fresh installs do not run Subspaces. Run **Enable
   Subspaces** to start it. It ships as the prebuilt `horologger/subs:v0.1.2c`
   image (no compile step), so enabling is fast — the daemons start as soon
   as the image is on the box. Enabling runs three daemons, each with its own
   StartOS interface: **subs** (Web UI + Subs API, 7777), **registry-server**
   (8081), and — only if the separate **Enable / Disable Subspaces Prover**
   toggle is on (default **off**) — **subs-prover** (8888, no GPU). The
   prover's interface is always registered even when its daemon is off. Before
   (or when prompted after) enabling, run **Create Registry API Keys** —
   `registry-server` requires distinct `REGISTRY_API_KEY` and `SUBSD_API_KEY`
   env vars at boot. Paste `SUBSD_API_KEY` into subs Settings → Registry
   Server → Auth Token, then click Test. Use `REGISTRY_API_KEY` as the Bearer
   token for intake/`POST /register` clients. subs loads the existing
   `default` spaces wallet at startup and does **not** create it — create it
   first from the Space-CLI Web UI with `spaces createwallet` if you haven't.
8. **Certrelay is always on.** It ships as the prebuilt
    `horologger/certrelay:v0.2.8` image (static musl binaries) and runs on
    7778 from service start. It talks to the local spaced over loopback using
    the `store.spacedAuth` credentials. The `fabric` and `monitor` binaries are copied to
    `/data/bin/` for manual use from the Space-CLI Web UI; neither is auto-started
    (only the certrelay server runs as a managed daemon). **You must
    set `CERTRELAY_SELF_URL`** (via **Configure Certrelay**) to the publicly
    visible URL StartOS exposes for the Certrelay interface, or peers/clients
    won't be able to reach this relay at the advertised address.

- `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 Space-CLI Web UI Credentials** action (the install task surfaces it).
2. Open the Space-CLI 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-user "$SPACED_RPC_USER" --rpc-password "$SPACED_RPC_PASSWORD" <subcommand>`.

Examples:

```bash
spaces getserverinfo
spaces createwallet           # creates the `default` wallet (--wallet defaults to "default")
spaces balance
```

## Quick Reference for AI Consumers

```yaml
package_id: spaces
upstream_version: subspacesplus
images:
  spaces: docker.io/horologger/spaces:v0.3.0
  subspaces: docker.io/horologger/subs:v0.1.2c
  certrelay: docker.io/horologger/certrelay:v0.2.8
  nacho: docker.io/horologger/nacho:v1.0.0b
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports:
  ui: 8080
  subspaces_ui: 7777    # external, only useful while subspaces enabled
  subspaces_prover: 8888  # external (its own interface), subspaces only
  subspaces_registry: 8081  # external (its own interface), subspaces only; remapped from upstream 8080
  certrelay: 7778       # external (its own interface), always on
  nacho: 8082           # external (its own interface), always on
  spaced_rpc: 7225      # external (Spaces API interface); spaced binds 0.0.0.0, auth-gated
dependencies:
  - bitcoind
spaced_env_vars:
  - SPACED_CHAIN
  - SPACED_DATA_DIR
  - SPACED_RPC_BIND
  - SPACED_RPC_PORT
  - SPACED_RPC_URL
  - SPACED_RPC_USER
  - SPACED_RPC_PASSWORD
  - 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
spaces:
  image: horologger/spaces:v0.3.0   # spaced, space-cli, gotty (terminal image)
subspaces:
  default_enabled: false   # opt-in via Enable Subspaces action
  store_field: enableSubspaces
  subs_prover_default_enabled: false   # separate toggle: set-subs-prover (store.enableSubsProver)
  image: horologger/subs:v0.1.2c   # prebuilt; no compile step
  data_dir: /data/subspaces/data
  wallet: default          # loaded by subs, NOT created (create via space-cli first)
  daemons:                 # three separate daemons, each its own interface
    subs: { bin: /usr/local/bin/subs, port: 7777 }
    subs-prover: { bin: /usr/local/bin/subs-prover, port: 8888, gpu: none }
    registry-server: { bin: /usr/local/bin/registry-server, port: 8081 }  # remapped from upstream 8080
  registry_api_keys:           # mandatory for registry-server boot; must differ
    store_fields: [registryApiKey, subsdApiKey]
    env_vars: [REGISTRY_API_KEY, SUBSD_API_KEY]  # always injected into registry-server
    generate: openssl-rand-hex-32   # 64 lowercase hex via create-registry-api-keys
    subs_ui: Settings → Registry Server → Auth Token = SUBSD_API_KEY
    actions:
      - create-registry-api-keys
      - show-registry-api-keys
  auth:                    # optional HTTP basic auth in front of subs (Web UI + Subs API on 7777)
    default_enabled: false
    store_enabled_field: subsAuthEnabled
    store_creds_field: subsAuth     # { username, password }; persists across enable/disable
    default_username: spaces
    env_vars:                       # injected only when subsAuthEnabled=true AND subsAuth!=null
      - SUBS_BASIC_AUTH_USER
      - SUBS_BASIC_AUTH_PASSWORD
    actions:
      - enable-subs-auth
      - disable-subs-auth
      - show-subs-credentials
      - set-subs-credentials
  prover_auth:             # optional HTTP basic auth in front of subs-prover (8888)
    default_enabled: false
    store_enabled_field: subsProverAuthEnabled
    store_creds_field: subsProverAuth
    default_username: spaces
    env_vars:                       # injected only when subsProverAuthEnabled=true AND subsProverAuth!=null
      - SUBS_PROVER_BASIC_AUTH_USER
      - SUBS_PROVER_BASIC_AUTH_PASSWORD
    actions:
      - enable-subs-prover-auth
      - disable-subs-prover-auth
      - show-subs-prover-credentials
      - set-subs-prover-credentials
certrelay:
  always_on: true
  image: horologger/certrelay:v0.2.8   # prebuilt; static musl binaries
  server_bin: /usr/local/bin/certrelay
  fabric_bin: /usr/local/bin/fabric    # copied to /data/bin/fabric for the CLI
  monitor_bin: /usr/local/bin/monitor  # copied to /data/bin/monitor (CLI only; not started)
  data_dir: /data/certrelay/data
  port: 7778
  spaced_rpc_creds: from store.spacedAuth (local spaced)
  configurable_via_action: configure-certrelay
  env:
    CERTRELAY_CHAIN: mainnet
    CERTRELAY_BIND: 0.0.0.0
    CERTRELAY_PORT: '7778'
    CERTRELAY_REMOTE_IP_HEADER: x-forwarded-for
    CERTRELAY_ANCHOR_REFRESH: '300'
    CERTRELAY_SELF_URL: https://certrelay.spacesops.com   # default; set to your public URL
    CERTRELAY_BOOTSTRAP: 'false'                          # toggle via action
    CERTRELAY_HEALTHCHECK_HANDLE: account-digital-useful.genesis@key  # via action
nacho:
  always_on: true
  image: horologger/nacho:v1.0.0b   # Expo dev server
  port: 8082
  data_dir: /data/nacho
  ignore_names_file: /data/nacho/ignore_names.txt  # read at runtime; default 'fold,swifty' seeded by nacho-setup
  configurable_via_actions:
    - configure-nacho        # ignore_names.txt + EXPO_PUBLIC_WORKSHOP_PDF_LINK_TEXT
    - upload-support-pdf     # writes /data/support.pdf
  env:
    EXPO_PUBLIC_API_BASE_URL: <derived from subs-api StartOS interface>
    EXPO_PUBLIC_WORKSHOP_PDF_LINK_TEXT: ''  # set via configure-nacho
    EXPO_DEV_PORT: '8082'
actions:
  - reset-password
  - show-credentials
  - show-password
  - set-bitcoin-rpc
  - show-spaced-credentials
  - sync-status
  - reset-spaced-state
  - export-wallet
  - import-wallet
  - enable-subspaces
  - disable-subspaces
  - set-subs-prover
  - enable-subs-auth
  - disable-subs-auth
  - show-subs-credentials
  - set-subs-credentials
  - enable-subs-prover-auth
  - disable-subs-prover-auth
  - show-subs-prover-credentials
  - set-subs-prover-credentials
  - create-registry-api-keys
  - show-registry-api-keys
  - reset-subspaces-state
  - configure-certrelay
  - configure-nacho
  - upload-support-pdf
```