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

## Limitations

- **Mainnet only.** No testnet, signet, or regtest.
- 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>