Self-hosting

You can run the entire Qubox stack on your own hardware, including the signaling relay and the TUF update repository. This page covers the two non-trivial components.

When to self-host

• You have a strict no-cloud policy (regulated industries, defense, privacy-first orgs).
• You want to pin to a specific version and never auto-update.
• You operate in air-gapped networks — the daemon can be configured to never reach the public internet.
• You run a large fleet and want to operate a single internal relay rather than dozens of direct connections.

If none of the above apply, the managed relay (free during beta) is the easier path.

Self-hosting the signaling relay

The signaling server is a single Rust binary. Minimum requirements:

• 1 vCPU, 512 MB RAM, 1 GB disk
• A reachable public IP with UDP 7000 open (configurable)
• A TLS certificate (Let's Encrypt is fine)

git clone https://github.com/qubox/qubox.git
cd qubox
cargo build --release -p qubox-signaling-server
./target/release/qubox-signaling-server \
    --bind 0.0.0.0:7000 \
    --state /var/lib/qubox/pairings.json

Run it under your favourite supervisor (systemd, runit, supervisord). A reference systemd unit ships in ops/signaling-server/.

For high availability, run two replicas behind a TCP/UDP load balancer. The pairing store is a small JSON file; for multi-replica deployments, mount a shared volume or use the planned Postgres backend (Q3 2026).

Self-hosting the TUF repository

The TUF repo lives at https://your-domain/.well-known/tuf/ and contains:

root.json
snapshot.json
targets.json
timestamp.json
1.0.0/
  qubox-linux-x86_64.tar.gz
  qubox-linux-x86_64.tar.gz.sig
  ...

The ops/tuf/init-tuf.sh script bootstraps a fresh repo with a generated root key. Store that key offline — losing it means you can never push another update.

To roll out a new release:

cd ops/tuf
./sign-release.sh \
    --target qubox-linux-x86_64.tar.gz \
    --version 1.2.0 \
    --repo https://qubox.app/.well-known/tuf/

This regenerates targets.json, snapshot.json, and timestamp.json with the new artifact included. Daemons polling the repo pick it up within their next refresh window (default 24h).

Air-gapped deployments

For networks with no internet egress:

1. Mirror the release artefacts onto an internal artifact server.
2. Mirror the TUF metadata to https://internal-mirror/.well-known/tuf/.
3. Pass --tuf-root <path> to qubox install on each host, pointing at your internal TUF root.
4. Configure --update-channel offline to skip network refreshes.

The daemon will still verify signatures, just against your keys, not ours.

Hardening checklist

• Bind the relay to a private interface, expose via reverse proxy
• Enable HTTP/3 if your reverse proxy supports it
• Rotate the TUF root key annually (or after a maintainer change)
• Back up the pairings store to encrypted off-site storage
• Set up Prometheus scraping on :9090/metrics
• Subscribe to security announcements

Operational runbooks

• ops/runbooks/relay-down.md — what to check when the relay stops responding
• ops/runbooks/tuf-key-rotation.md — the offline procedure
• ops/runbooks/daemon-upgrade-failure.md — manual rollback steps

What we don't (yet) support

• Multi-region active-active relays — the JSON store doesn't support concurrent writes from multiple replicas. Use the managed relay for that, or wait for the Postgres backend.
• WebTransport gateway — no browser clients. Use the CLI/GUI.
• Custom TUF root rotation via the daemon — you must run sign-release.sh on a workstation, not on the daemon itself.