<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 |
| --- | --- |
| Image | `docker.io/horologger/spaces` |
| Architectures | `linux/amd64`, `linux/arm64` |
| Entrypoint | StartOS-managed (image entrypoint is **not** used) |

The image bundles `spaced`, `space-cli`, `bitcoin-cli`, `gotty`, `node`, `npm`,
`screen`, and a small shell environment. StartOS ignores the 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 (web-UI password + bitcoind RPC user/password) |

## 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 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. Launches `spaced` as a managed daemon (no `screen`, no shell auto-start).
4. Launches the `gotty` web terminal once `spaced` is up.

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 |
| Chain selection (locked to `mainnet`) | `space-cli` flags and subcommands |
| Spaced data directory and RPC bind |  |

## Network Access and Interfaces

| Interface | Port | Protocol | Exposure | Notes |
| --- | --- | --- | --- | --- |
| Web UI (gotty terminal) | 8080 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | Basic auth: `admin:<store.password>` |
| Spaced RPC | 7225 | HTTP JSON-RPC | **Loopback only** | Internal use, cookie-authenticated |

## Actions

| ID | Name | Visibility | Availability | Purpose |
| --- | --- | --- | --- | --- |
| `reset-password` | Reset Web UI Password | Enabled | Any | Regenerates the web-UI password and restarts the terminal daemon |
| `show-credentials` | Show Web UI Credentials | Hidden | Any | Surfaces the current `admin` username + masked password (launched by the first-install task) |
| `set-bitcoin-rpc` | Set up Bitcoin RPC | Enabled | Any | Re-invokes bitcoind's `generate-rpc-dependent` with the stored credentials. Safe to call repeatedly. |
| `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. |

## 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 `127.0.0.1:7225` |
| `web-terminal` (daemon `ready`) | Web Interface | default | TCP listen on `0.0.0.0:8080` |
| `sync` (standalone) | Spaced Sync | 300 s | Exec `space-cli getserverinfo`; reports `success` when `ready=true`, otherwise `loading` with progress percentage |

## Limitations and Differences

1. **Mainnet only.** Testnet, testnet4, signet, and regtest are not exposed.
2. **The image's `docker_entrypoint.sh` is not used.** Its auto-start of
   `spaced` inside `screen` would conflict with the StartOS-managed daemon.
3. **Web UI is a terminal, not a graphical app.** All Spaces operations happen
   via `space-cli` (aliased as `spaces` inside the shell).
4. **Only port 8080 (gotty) is exposed.** Spaced RPC, and any other ports
   present in the image (e.g. 22253, 3000, 5173, 8081) are not bound.
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.

## What Is Unchanged from Upstream

- `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 Web UI Credentials** action (the install task surfaces it).
2. Open the 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-cookie /data/mainnet/.cookie <subcommand>`.

Examples:

```bash
spaces getserverinfo
spaces walletcreate default
spaces walletbalance default
```

## Quick Reference for AI Consumers

```yaml
package_id: spaces
upstream_version: subspacesplus
image: docker.io/horologger/spaces:v0.0.9s
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports:
  ui: 8080
  spaced_rpc: 7225  # loopback only
dependencies:
  - bitcoind
startos_managed_env_vars:
  - SPACED_CHAIN
  - SPACED_DATA_DIR
  - SPACED_RPC_BIND
  - SPACED_RPC_PORT
  - SPACED_RPC_URL
  - 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
actions:
  - reset-password
  - show-credentials
  - set-bitcoin-rpc
  - sync-status
  - reset-spaced-state
```