namek-server

namek-server

Orchestrator for Piccolo OS — handles device authentication, DNS orchestration, and certificate issuance.

Install

Piccolo OS (Recommended)

If you're running Piccolo OS, Namek is available as a one-click install from the Piccolo Store. Open the portal, find Namek, and click install — no configuration required.

Self-Hosted

For running Namek independently. Requires Go 1.24+, PostgreSQL 16+, and PowerDNS.

git clone https://github.com/AtDexters-Lab/namek-server.git
cd namek-server
make build                          # outputs bin/namek
cp config.example.yaml config.yaml  # edit for your environment
./bin/namek -config config.yaml

All config fields are annotated in config.example.yaml. For a production Docker Compose setup, see deploy/.

Verify it's running:

curl -k https://localhost/health    # 200 OK — server is up
curl -k https://localhost/ready     # 200 OK — database connected

What It Does

Namek is the control plane for Piccolo OS deployments. It handles the responsibilities that neither the on-device daemon nor the edge proxy should own:

• Device authentication & attestation — Verifies device identity via TPM 2.0 and issues tokens for Nexus relay registration.
• DNS-01 ACME orchestration — Manages TXT records so piccolod can obtain wildcard TLS certificates without exposing port 80.
• Account management — Links user accounts to their registered devices.
• Custom domain support — Users can bring their own domains with DNS-based ownership verification.

Where It Fits

┌──────────────┐       ┌──────────────┐       ┌──────────────────┐
│   piccolod   │◄─────►│ Namek Server │◄─────►│  Nexus Proxy     │
│  (on device) │       │(orchestrator)│       │  (edge relay)    │
└──────────────┘       └──────────────┘       └──────────────────┘
       │                      │
       │  Device attestation  │  DNS-01 challenges
       │  Token issuance      │  Account & domain management

• piccolod runs on the user's hardware, serves the local portal, and connects to Nexus for remote access.
• Nexus Proxy is a privacy-first TLS passthrough relay — it never sees plaintext traffic.
• Namek Server coordinates between them: authenticating devices, managing DNS for certificate issuance, and brokering account and domain operations.

All three components are open source and self-hostable. Users who run their own Nexus and orchestrator need no account and pay nothing. For the full architecture, see the piccolo-os README.

API

Namek exposes a REST API over HTTPS with health probes at /health and /ready, device enrollment and operations under /api/v1/, and Nexus-internal endpoints under /internal/v1/ (mTLS).

Operator endpoints (census, fleet health, recovery) are available on the admin listener — see adminAddress in config.example.yaml.

Full specification: api/openapi.yaml (OpenAPI 3.1)

Development

make dev-deps   # starts Postgres, PowerDNS, Pebble via Docker Compose
make dev        # builds and runs with config.dev.yaml
make test       # runs tests with race detector
make dev-down   # tears down Docker services

Docs

• piccolod integration spec — how the on-device daemon talks to Namek
• Nexus integration spec — relay registration and token verification
• RFCs — design documents covering architecture, custom domains, fleet trust, resilience, and more

Planned: PSFN Broker

In a future phase, Namek will also broker the Piccolo Storage Federation Network (PSFN) — where Piccolo devices replicate data across a peer mesh for durability:

• Peer discovery and negotiation
• Health scoring and network topology
• Per-tenant encryption enforcement with TPM attestation

The Piccolo Ecosystem

License

AGPL-3.0 — see LICENSE.