97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# 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.1`; Subspaces, Certrelay, and Nacho use
|
|
`horologger/subs:v0.1.2d`, `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>
|