Vonk Forge
Local AI. One private control plane.
Vonk Forge is an open-source control plane for NVIDIA DGX Spark. Run the
controller on any local computer with Docker Compose—including your laptop—then
use one private Web interface or the vonkctl CLI to discover model recipes,
preview changes, and operate one Spark or a fleet.
Install Vonk Forge ·
See how it works ·
Browse recipes ·
Read the operator docs
The screenshot is produced by the repository's fixture-backed browser
acceptance suite. It contains no live fleet data.
What it gives you
- One place to operate local AI. Fleet, Library, Activity, and reusable
fleet profiles share one controller and one source of truth.
- Cache-backed profiles. Profile choices and apply admission come from the
trusted local NAS/Controller cache, which resolves exact model and
recipe-image identities.
- One profile for the fleet. Reviews include every current enrolled,
non-revoked Spark and show unassigned Sparks as idle. A membership change
before applying requires a fresh review. The
operator guide describes target behavior
when Sparks later join or leave.
- A safer change path. See compatibility, placement, downloads, memory,
and the exact planned change before you apply it.
- Reproducible model recipes. Recipes bind model, runtime, topology,
capacity, source, and qualification facts to immutable identities.
- No routine Spark SSH. A native Rust agent connects outbound and executes
controller-authorized work after enrollment.
- Your infrastructure stays authoritative. The controller, PostgreSQL
state, identity, secrets, model caches, and fleet state remain local.
The 30-second mental model
flowchart LR
Catalog[Public recipe catalog<br/>metadata and verified source]
Controller[Your local controller<br/>Web UI, API, PostgreSQL, policy, profile cache]
SparkA[DGX Spark<br/>agent, execution cache, runtime]
SparkN[More Sparks<br/>enroll when needed]
Catalog -->|verify and import| Controller
Controller -->|admit and prepare exact assets| SparkA
Controller -->|same local authority| SparkN
The public website is documentation and catalog—not a hosted admin surface.
The trusted local NAS/Controller cache is the authority for profile choices and
apply admission. Model and recipe-image assets remain tied to immutable
identities there before an apply distributes them to Sparks. Spark-local copies
are execution caches, not profile authority; normal cache trust does not imply
costly repeated full hashing.
Install
1. Prepare the controller project
The installer defaults to Secure remote, which connects the existing
Tailscale gateway. Lab mode (LAN only, no Tailscale) is available as an
explicit choice: answer lab at the install mode prompt. Lab mode needs only
the NAS LAN address and an optional Hugging Face token; internal passwords,
keys, and the local CA are generated for you. See the
Lab quickstart.
For Secure remote, complete the
Tailscale preflight: enable
MagicDNS and HTTPS, define the exact unsuffixed Services, apply the reviewed
grants and auto-approvals, and create the scoped gateway OAuth client. Never
add test-only Service names or policy to an operator tailnet.
Prepare on Intel or ARM macOS or Linux with curl, openssl and
installed uv. The verified NAS setup wheel runs in an isolated Python 3.14
environment managed by uv; no native NAS setup compilation is required.
Then run:
curl -fsSL https://install.vonkforge.ai/nas | sh
The signed interactive installer verifies the exact Python NAS setup wheel and
NAS payload, then creates one portable, private project:
vonk-forge/
├── docker-compose.yaml
├── .env
└── secrets/
Until the first stable release is published, the unqualified /nas, /spark
and /vonkctl URLs serve the newest accepted development release; once a
stable release exists they serve stable. To choose a channel explicitly, use
https://install.vonkforge.ai/dev/nas (or /dev/spark, /dev/vonkctl).
To upgrade an existing install, rerun the installer from the directory that
contains vonk-forge/, using the account that owns its private files. If they
belong to root, or you need to repair the configured secret group with existing
administrative authority, put sudo on the sh side of the pipe.
sudo curl ... | sh does not work. uv must be available to that account:
curl -fsSL https://install.vonkforge.ai/nas | sudo sh
.env and secrets remain private to their owner. For a root-owned project, run
docker compose with sudo on the host.
The /nas path in the public installer URL is historical; the generated
project is not NAS-specific. Keep it on this laptop for a lab, or move the
complete directory to a NAS or local server for an always-on controller.
2. Start it on your chosen Docker Compose host
With a shell on that host:
cd vonk-forge
sudo docker compose pull
sudo docker compose up -d --wait --remove-orphans
sudo docker compose ps
In a NAS or server UI, select the same directory as one Compose project and
start docker-compose.yaml. Keep .env and secrets/ beside it.
3. Add a Spark
Open the controller's private Web address, go to Fleet, and create a one-use
enrollment grant with Enroll Spark. Enter a display name, then run the
generated command on the Spark before the displayed expiry. The installer asks
for the one-use pairing token shown with the command. It has this shape:
curl -fsSL https://install.vonkforge.ai/spark | VONK_CONTROLLER_ADDRESS=192.168.1.231 VONK_ENROLLMENT_URL=https://enroll.example.test VONK_CONTROLLER_CA_SHA256=<fingerprint> sh -s -- --enroll
Use the stable LAN address of your laptop, NAS, or server. The installer verifies
the immutable release, enrolls the native agent, writes the required agent and
firewall configuration, and checks service health. Repeat with a new one-use
grant for each additional Spark.
For a headless Spark, use SoC firmware 0x02009e0f or newer (the
DGX Spark SoC FW System Update in fwupdmgr get-devices; update with
fwupdmgr update). In UEFI, set Advanced → Advanced Menu → Display Reserved
Memory → 0.5 GB (fixed), save, and reboot. Fixed 0.5 GB gives a deterministic
pool independent of a monitor at boot; Auto booted headless also reserves 0.5 GB
and counts as configured. Compared with the default 2 GB, this releases exactly
1.5 GiB on the measured Sparks. After updating firmware, power-cycle if
nvidia-smi shows ERR! or “GPU requires reset” after a warm reboot. See NVIDIA's
UEFI guide.
Vonk's root helper reads /proc/iomem during each inventory (unprivileged reads
hide the addresses). The measured reserved block ending at 0x3237fffff includes
0x23800000 bytes of other firmware memory: the measured 0xA3800000 and
0x43800000 blocks therefore identify 2 GB and 0.5 GB of display memory.
Anything else remains unknown, including masked addresses and MemTotal alone.
Fleet advice is non-blocking and appears only above 0.5 GB on a headless Spark;
Vonk never changes firmware or UEFI. A minimum reservation does not distinguish
fixed 0.5 GB from Auto booted headless.
Install vonkctl
Install the latest accepted stable CLI without cloning the repository. This
requires curl, openssl, Python 3, and uv on your workstation. The CLI
requires Python 3.14 or newer, which uv can manage for its tool environment:
curl -fsSL https://install.vonkforge.ai/vonkctl | sh
The installer verifies the signed channel and immutable release, then checks
the wheel's digest, size, and build identity before uv installs it. See the
vonkctl runbook for development-channel and
verification details.
The same controller command prepares upgrades while preserving local identity
and secrets. Running the Spark installer on an enrolled node performs an in-place
agent upgrade; certificate replacement is an explicit Fleet re-enrollment.
Daily operation
| Stage | What you see before moving on |
|---|
| Find | Cache-backed model and recipe choices filtered against the fleet you own |
| Preview | Compatibility, placement, capacity, exact assets, and actionable blockers |
| Prepare | Resolve missing NAS model or recipe-image assets with the prepare-cache action |
| Apply | A ready, digest-bound plan prepares exact assets in parallel, skips local copies, and safely replaces workloads |
| Observe | Live Fleet state, per-target progress, warnings, recovery, and audit history |
The private Web Controller is the guided path. vonkctl exposes the same API,
filters, previews, mutations, and JSON output for repeatable operations. See the
complete CLI guide.
Security boundary
| Public | Local controller | DGX Sparks |
|---|
| Documentation, signed installers, recipe metadata, verified source | PostgreSQL authority, policy, service identity, runtime secrets, trusted profile cache, previews | Enrolled agent identity, execution caches, runtime execution, telemetry |
- The public site never controls Sparks or receives runtime secrets, fleet
state, controller authority, or model uploads.
- Agents connect outbound with independently enrolled identity.
- Secret values live in controller-owned files, not Git, command arguments, or
captured diagnostics.
- Model weights and recipe images are resolved from immutable identities in the
local cache, then prepared on target Sparks; already-local assets are skipped.
They do not pass through the public catalog. NAS cleanup removes unused local
model-cache entries while preserving profile and active-workload references.
For the trust and network model, see the
architecture guide and
threat model.
Repository map
| Area | Purpose |
|---|
control/ | FastAPI controller, PostgreSQL authority, migrations, and Web Controller |
nas_setup/ | Portable Python NAS/project setup wheel and recovery |
rust/ | Native Spark agent, privileged helpers, installer and local enforcement |
deploy/ | Signed controller/Spark installation and Compose contract |
scripts/ | Validation, import, publication, and operator tooling |
docs/ | Architecture, security, runbooks, and contributor policy |
The public recipe standard library lives in
CarstVaartjes/vonk-forge-recipes.
The public website and catalog implementation live in
CarstVaartjes/vonk-forge-web.
Develop
Required tools are Python 3.14+, uv, Rust,
Node.js, and Docker for integration tests.
Catalog tests consume the real recipe repository. Set
VONK_RECIPE_LIBRARY_ROOT to your checkout; CI checks out and records an exact
revision. The examples below use the standard /opt/vonk-forge-recipes path.
export VONK_RECIPE_LIBRARY_ROOT=/opt/vonk-forge-recipes
uv sync --dev
scripts/build-control-wheel
# Fast tier: hermetic and parallel, no Docker/PostgreSQL/cargo/host tooling.
uv run --project control --frozen \
pytest -q control/tests -m "not lane" -n auto --dist loadfile
uv run --project control --frozen pytest -q tests -m "not lane" -n auto
# Lane tier in the container or CI lane.
scripts/pull-test-images postgres caddy tailscale python
uv run --project control --frozen pytest -q control/tests
uv run --project control --frozen pytest -q tests
# Web and compose boundaries, then release evidence.
npm ci --prefix control/web
npm test --prefix control/web -- --run
uv run --frozen pytest -q deploy/compose/tests
scripts/verify-supply-chain --json
Start with the documentation index,
Compose deployment notes, and
testing policy.
License
Vonk Forge is available under the MIT License.
