Documentation

Nova docs

The operator, donor and protocol documentation from Nova's repository, rendered here so it can be read without cloning anything. It tracks main, so it follows the source rather than being kept in step by hand.

Where a page and the repository disagree, the repository wins. Design notes and milestone plans are not published here; links to them lead to the source tree.

Reference

API reference

Every HTTP endpoint a Nova coordinator exposes, with parameters, example requests and the meaning of each status code. Generated from docs/specs/openapi.yaml.

Open the API reference

Spec version: 0.2.0-beta.1+ad629d7
OpenAPI: 3.1.0
Operations: 66 across 9 groups

Start here

Documentation
Nova Operator Quickstart: This walkthrough takes you from a fresh clone to a running Nova node that serves an uploaded image over HTTPS. At the end you will have:
Quickstart screenshots — capture checklist: docs/quickstart.md and the main README.md reference five screenshots of the first-run setup wizard. They are captured and present in this directory; this checklist is the recapture spec…
Running a Nova donor node: You are lending some disk and some bandwidth to someone's Nova archive. Your machine stores encrypted pieces of their data and hands them back when asked.
Turning on federation: This is the whole path from a running Nova operator to a donor storing your data. Eight steps, about fifteen minutes.

Operating a federation

Deployment Recipes: Annotated deployment recipes for common operator scenarios. Each recipe is operator-side: it builds on Nova's existing primitives rather than changing the protocol. The Nova binaries do…
Recipe: Annotated nginx reference configuration: Walks through nginx/nova.conf.example line by line, explaining why each directive is set the way it is and which choices the operator should adapt to their environment.
Recipe: Automated donor onboarding: Status: Operator-side pattern. Nova does not ship this. The protocol provides cryptographic primitives (cert issuance, revocation, reputation, possession audits); this document describes…
Recipe: Cloudflare CDN fronting (optional, with significant caveats): bandwidth costs at the origin would otherwise be prohibitive.
Recipe: Cold-standby coordinator for read availability: Status: Operator-side pattern. Nova does not ship the failover orchestration. The architecture is compatible with manual cold standby; this document describes how an operator can set one up.
Recipe: Master-key backup escrow: Status: Operator-side pattern. Nova does not ship this. The running coordinator continues to load the unwrapped master key from NOVAMASTERKEY; the escrow pattern only applies to backups…
Runbook: donor lifecycle (revoke / suspend / drain / below-floor): Drain is never the tool for a hostile node — a hostile node must not remain a read/repair source, which is exactly what a draining node stays.
Runbook: failure drills (provider loss / disk full / corrupt donor state): What you'll see. Every node in the domain stops heartbeating; after the liveness thresholds they sweep suspect → unreachable:

For donors

Volunteer Deployment Guidance: A short, practical guide for community members who want to run a donor pinning node for a Nova federation. Aimed at volunteers, not operators; this is the document a federation's invite…

Specifications

Architecture Decisions: Status: Phase 0 v3 — normative. Classifies every architectural decision Nova has made into one of three tiers. Future contributors proposing a change must identify which tier the change…
Encryption Envelope: Status: Phase 0 v3 — normative. internal/envelope must conform exactly.
Federation Protocol: Status: Phase 0 v3 — normative. internal/federation (coordinator side) and cmd/node (donor side) must conform exactly.
Healing Protocol: Status: Phase 0 v3 — normative. Specifies the orchestrator's bandwidth-aware healing algorithm. internal/orchestrator (Phase 2) implements this protocol. The simulation under…
IPFS Daemon Hardening: Status: Phase 0 — normative. Donor pinning nodes refuse to start unless the embedded Kubo daemon's configuration satisfies the rules below. The coordinator's own embedded Kubo runs the…
IPFS Import Rules: Status: Phase 0 — normative. internal/ipfs must conform exactly.
Integrity Audit: Status: Phase 1 deliverable, normative. internal/audit/integrity must conform exactly.
Possession Audit: Status: Implemented (P2-M6, 2026-06-29). internal/audit/possession is the normative implementation. Design:…
Product Module Interface: Status: Phase 0 v2 — normative. Defines how content-type-specific product layers (nova-image first, future nova-video, nova-audio, nova-archive, nova-document) plug into the storage core…
Signed URL Format: Status: Phase 0 v2 — normative. Implementations of internal/auth must conform exactly. Drift between this spec and the implementation is a bug in the implementation.
Specifications: This directory contains the load-bearing specifications for Nova. Production code in cmd/, internal/, pkg/, and web/ implements these specs faithfully. Drift between code and spec fails CI.
Threat Model: Sybil / failure-domain concentration. Placement anti-affinity and the concentration metrics (per-node Gini, per-dimension largest-share / normalized entropy) trust a dimension value only…

Security and privacy

Privacy Audit: Status: Phase 0 — normative for the privacy posture of the production stack. This document tracks the telemetry / phone-home / fingerprinting behaviour of every dependency Nova ships…
Threat Model: Status: Phase 0 — normative for what is in scope and out of scope. This document is engineering reasoning, not legal advice. Operators should consult counsel in their jurisdiction before…

Project

Nova — developer setup: This is the lightest dev-test path: boot a single-node coordinator against a local Postgres + embedded IPFS to kick the tires. It does not replace the production first-run, which uses…
Roadmap: Lock the protocol and contracts as documents before any production code is written. The original Phase 0 was completed, then revised in a v2 consistency pass after design audits…
Versioning: Nova follows semantic versioning and treats every milestone as a distinct, uniquely versioned release. No two variations of Nova — however small the change — carry the same version number.

Legal

Legal: Templates and procedures the operator must adopt when running Nova.
Operator Checklist: A pre-launch and ongoing checklist for site operators running a Nova coordinator. v2 narrows the [REQUIRED] set to only what the coordinator literally cannot run safely without;…
Severe Content Procedure: Status: Phase 1 — manual operator path ships (M9). Full automation Phase 4.
Takedown Procedure: The internal procedure for receiving, validating, processing, and acting on takedown notices. This document is the operator's runbook; the user-facing contract is in the Terms of Service.
Terms of Service Template: Effective date: {{EFFECTIVEDATE}}

Other

Donor configuration reference: Every field in node.yaml, what it does, and what happens if you change it.
Operator configuration reference: Settings an operator can change, what they do, and the consequences.
Releasing Nova: How a Nova release is cut, who approves it, what the workflow refuses, and what has to be configured on GitHub for any of it to work.
Running a donor on Windows (WSL2): WSL2 works as a donor host. WSL1 does not. There are four things to get right, and one expectation to set.
Upgrading Nova: Normative. Every step an upgrade needs is on this page; if an upgrade requires something that is not written here, that is a bug — report it rather than improvising. Manual out-of-band…

Generated 2026-09-11 09:26 UTC