working

instructions.md

@@ -0,0 +1,64 @@
+# 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>