Specter on StartOS

Upstream docs: https://docs.specter.solutions/

Everything not listed in this document should behave the same as upstream Specter Desktop. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

A Bitcoin wallet UI focused on multisig and hardware wallet workflows. See the upstream repo for general Specter documentation.

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Actions (StartOS UI)
• Backups and Restore
• Health Checks
• Dependencies
• Limitations and Differences
• What Is Unchanged from Upstream
• Quick Reference for AI Consumers

---

Image and Container Runtime

Property	Value
Image	Upstream ghcr.io/cryptoadvance/specter-desktop
Architectures	x86_64, aarch64
Entrypoint	python3 -m cryptoadvance.specter server --host 0.0.0.0

Volume and Data Layout

Volume	Mount Point	Purpose
main	/data	All Specter data (.specter/)

StartOS-specific files written to the main volume:

File	Purpose
.specter/config.json	Tracks the selected backend (Bitcoin RPC vs Spectrum Node) and the chosen Spectrum sub-backend. Managed by the Select Node action.
.specter/nodes/bitcoin_core.json	Bitcoin RPC node entry — host, port, protocol, and the dependency-scoped RPC user/password generated for Specter.
.specter/nodes/spectrum_node.json	Spectrum Node entry pointing at the selected Electrum backend (electrs or Fulcrum), resolved to its address on the StartOS service (LXC) bridge.

Installation and First-Run Flow

1. On first install (or any time config.json.active_node_alias is unset) StartOS creates a critical task prompting the user to run Select Node.
2. Select Node defaults to Bitcoin RPC — the reliable, recommended path. The user can switch the variant to Spectrum Node (experimental) and, within Spectrum, choose Fulcrum or electrs as the backend.
3. When Bitcoin RPC is chosen, Specter generates a fresh dependency-scoped RPC username/password and dispatches generate-rpc-dependent to the bitcoind service so the credentials are appended to its rpcauth. If a bitcoin_core.json already contains usable credentials, they are reused instead.
4. When Spectrum Node is chosen, the Spectrum Node entry is wired to the selected indexer (Fulcrum or electrs), reached at its plain-TCP Electrum address over the StartOS service (LXC) bridge (TLS off). The chosen indexer in turn requires a Bitcoin node — that's a dependency of the indexer, not of Specter directly.
5. Specter starts and serves its web UI on port 25441.

Configuration Management

StartOS-Managed	Details
Active backend	Bitcoin RPC vs Spectrum Node — set by the Select Node action
Spectrum sub-backend	electrs or Fulcrum, when Spectrum Node is selected
bitcoin_core.json host/port/protocol	bitcoind's RPC address, resolved over the StartOS service (LXC) bridge, over HTTP
Bitcoin RPC credentials	Generated and registered on the bitcoind service via generate-rpc-dependent; reused if already present
spectrum_node.json host/port	The selected indexer's Electrum address, resolved over the StartOS service (LXC) bridge, ssl: false

Everything else (wallet creation, multisig, devices, fees, block-explorer URLs, etc.) is configured through Specter's own web UI.

Network Access and Interfaces

Interface	Port	Protocol	Purpose
Web UI	25441	HTTP	Specter web interface

Actions (StartOS UI)

Select Node

• Name: Select Node
• Purpose: Choose the Bitcoin backend Specter should connect to
• Visibility: Enabled (always visible)
• Availability: Any status
• Inputs:
  • Node — Bitcoin RPC (recommended) (default) or Spectrum Node (experimental)
  • Spectrum Backend — Fulcrum (default) or electrs. Only shown when the Spectrum Node variant is selected.
• Outputs: A success message describing what was configured

Backups and Restore

Backed up: the entire main volume — wallet metadata, the .specter configuration tree, and the StartOS-managed node entries described above.

Restore behavior: Standard restore. After restore, the configured backend must be installed and running. If config.json.active_node_alias is missing, the install task re-prompts the user to run Select Node.

Health Checks

Check	Method	Messages
Web Interface	Port listening on 25441	Success: "The web interface is ready" / Error: "The web interface is not ready"

Dependencies

Dependency	Required	Version	Health checks	Purpose
Bitcoin (bitcoind)	Optional	>=28.3:0	bitcoind, sync-progress	Native RPC backend (satisfied by Bitcoin Core or Bitcoin Knots, which share the bitcoind package id)
electrs	Optional	>=0.10.0:0	electrs, sync	Electrum server reached via Spectrum Node
fulcrum	Optional	>=2.1.0:0	primary, sync-progress	High-performance Electrum server reached via Spectrum Node

The active dependency is determined at runtime from config.json. Exactly one of the three is required and must be running, depending on the user's Select Node choice.

Limitations and Differences

1. Backend choice is a one-shot selection — switching backends requires re-running the Select Node action.
2. Spectrum endpoint uses plain TCP with TLS off — the indexer's bridge address is resolved automatically; not user-configurable from inside Specter.
3. Bitcoin RPC uses bitcoind's bridge address over HTTP — same reason; users do not enter RPC details manually.
4. No HWI Bridge integration — Specter runs server-only; hardware wallet support is via Specter's web UI flows (USB pass-through is not provided by the StartOS package).

What Is Unchanged from Upstream

• All wallet, multisig, and PSBT workflows
• Hardware wallet integration via the Specter web UI
• Tor / proxy settings, block-explorer URL settings, language, and other Specter settings
• Wallet import/export, descriptor handling, and the Specter API

Quick Reference for AI Consumers

package_id: specter
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports:
  ui: 25441
dependencies:
  - bitcoind (optional)
  - electrs (optional)
  - fulcrum (optional)
startos_managed_files:
  - .specter/config.json
  - .specter/nodes/bitcoin_core.json
  - .specter/nodes/spectrum_node.json
actions:
  - select-node
health_checks:
  - port_listening: 25441
backup_volumes:
  - main