# Spaces

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.

## 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:

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