Lattice

Lattice is the umbrella repository for the LatticeNet ecosystem: a security-first server probe, automation, and cluster network control plane.

The code is intentionally split into independent repositories so server, node-agent, dashboard, SDK, and plugins can be released and maintained separately.

Ecosystem Repositories

• lattice-sdk - shared Go protocol/domain models.
• lattice-server - deployable control plane.
• lattice-node-agent - deployable outbound node agent.
• lattice-dashboard - static dashboard.
• lattice-plugin-template - starter templates for system, Worker, and future Wasm plugins.
• .github - organization profile.

Current MVP

• Go server and Go node-agent.
• Outbound agent enrollment, heartbeat, metric/HostFacts reporting, task polling, and task result upload.
• Machine inventory profiles for vendor/region/cost/renewal tracking, encrypted console/detail links, and renewal reminders.
• Session login, CSRF checks, TOTP 2FA, OIDC/SSO, PBKDF2 password/token hashing, PAT scopes, server allowlists, and tamper-evident audit WAL.
• Node dashboard, task runner, KV, static bucket, Worker registry, SSO provider admin, plugin lifecycle/runtime health, network guard, saved network policy intent/SVG graph, egress-only NetPolicy apply planning, Fleet Map, approvals, and audit views.
• nftables plan generation with explicit approval before apply, including an applied lattice_guard Network Guard path and an egress-only NetPolicy path, both with agent-side rollback/selfcheck where the server public URL is known.
• Self-host DNS deployment intent, CoreDNS/nft planning, rollback-protected apply, Cloudflare hostname publication, separate service/publish status, and optional pinned CoreDNS executable install.
• Geo-Routing configure+preview for a self-hosted DNS apex, using operator-owned node locations and healthy-node selection.
• Log ingestion/query MVP with a dedicated bounded logs.db, agent tailer, scoped source management, and dashboard Logs panel.
• Server-controlled node-agent update policies with manual update plans, auto-plan pending approvals, SHA-256-pinned HTTPS artifacts, and delayed service restart after task result reporting.
• Proxy-core/subscription foundation: shared models, redacted proto views, JSON/bbolt persistence, and encrypted Reality/user/subscription credentials plus the first fail-closed sing-box vless+TCP+REALITY renderer, scoped CRUD/read APIs that return secret-free views, a redacted reviewed plan endpoint that binds the real rendered config hash, and secret-safe reviewed queue/apply with encrypted task scripts, sing-box check, atomic config swap, task-result status reconciliation, and a public plain/base64 /sub/{token} MVP with Subscription-Userinfo, dedicated rate limiting, hashed-token audit, duplicate-token fail-closed handling, sing-box JSON and Clash/Mihomo YAML subscription formats for VLESS+REALITY+TCP, plus dashboard inbounds/users/profiles management, an explicit audited rotate/copy subscription URL workflow, and a baseline usage-reporting path with server-side monotonic rollup plus dashboard usage/last-seen display.
• Operator-owned NodeGeo records and a dependency-free dashboard world map.
• Static TypeScript source and dependency-free browser assets.
• Local AES-256-GCM encrypted JSON storage plus an append-only hash-chained audit WAL. The storage interface is isolated; the planned durable engine is bbolt to preserve the pure-Go / zero-CGo constraint. The server now has an explicit JSON↔bbolt migration/export CLI plus record-level bbolt APIs for current state buckets; JSON remains the default runtime store.

Quick Start

Docker server deployment:

cd Lattice/lattice/compose
cp .env.example .env
$EDITOR .env
docker compose up -d

See Docker server deployment. The recommended production shape is containerized lattice-server plus a systemd-managed host lattice-node-agent.

Local binary development:

cd Lattice/lattice
make test
make build
LATTICE_ADMIN_PASSWORD='change-this-passphrase' make run-server

Open http://127.0.0.1:8088. The default username is admin. If LATTICE_ADMIN_PASSWORD is not set on the first run, the server prints a random bootstrap password to stdout.

Enroll a node from the dashboard, then run:

cd Lattice/lattice-node-agent
go run ./cmd/lattice-agent \
  -server http://127.0.0.1:8088 \
  -node-id demo-node \
  -token '<enrollment-token>' \
  -allow-exec=false

Task execution is disabled by default on the agent. Start with -allow-exec=true only on machines where you accept the risk.

Design Defaults

• Agents dial out; inbound node ports are not required.
• Dangerous operations follow plan -> diff -> approve -> apply.
• Plugins must pass signed-manifest verification before lifecycle registration. Active plugins receive only a capability-scoped broker through the runtime runner contract; artifact execution is still disabled by default.
• Management APIs should live on WireGuard/private addresses or behind a hardened reverse proxy.

Operator Docs

• Tutorial index
• Operator guide
• Server install
• Agent install
• Agent updates
• Storage migration drills
• Plugins
• Network guard
• Development report, 2026-06-13

Contributor Docs

• Development workflow

Repository Creation Order

Publish lattice-sdk first, then lattice-server and lattice-node-agent, then lattice-dashboard, lattice-plugin-template, lattice, and .github.

Shared Contract Releases

lattice-server and lattice-node-agent intentionally consume shared models from lattice-sdk. When SDK contracts change, cut a new lattice-sdk tag first and then update the dependent go.mod files. Local multi-repo development can use go.work, but standalone builds should not depend on an untagged SDK main.

Current dependent SDK version: v0.2.0.