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, plugins, and mobile companion surfaces 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.
• Astra - iOS companion app for the Lattice mobile control surface.

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.
• Browser terminal MVP with scoped terminal:open, opt-in agent-side PTY sessions, xterm rendering, node-level dashboard entrypoints, bounded in-memory I/O, and audited open/close events.
• 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.
• Astra iOS companion app v2 for phone-first operations: Overview, Nodes, Monitors, Inventory, and More tabs backed by a Swift LatticeClient for identity/version, nodes, PATs, machine inventory, monitors/results, Network & security read views with SHA-256-bound approval, notifications, audit, tasks, and logs. Source is published in LatticeNet/Astra; signing, TestFlight, and live iPhone QA remain separate release steps.
• 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. For fleet-wide incident response, start lattice-server with LATTICE_TASK_EXEC_DISABLED=1 / -task-exec-disabled; the server will reject new task queueing and return no leases to agents while still accepting results from tasks that were already leased. Linux agents can also enforce optional per-task cgroup v2 caps for resident memory, pids, and CPU by setting LATTICE_TASK_CGROUP_ROOT=auto (or an absolute delegated cgroup root). Cgroup caps are off by default and fail closed when configured but unavailable, so tasks do not silently run without the requested OS-level limit. Linux task interpreters also run with no_new_privs, blocking setuid or file-capability privilege gain from task scripts. Set LATTICE_TASK_WORK_ROOT=/opt/lattice/state/tasks to place task-private working directories under an operator-controlled root. Each task gets its own removed-after-run directory, and the agent binds HOME, TMPDIR, and XDG_RUNTIME_DIR to it. On Linux, task scripts also inherit umask 077. This reduces temp-file leakage but is not a full mount namespace or filesystem sandbox. For least-privilege Linux systemd installs, set LATTICE_AGENT_RUN_USER=lattice-agent before running the agent installer; use a root-capable service profile only for host mutation or self-update tasks.

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, lattice-node-agent, lattice-dashboard, lattice-plugin-template, lattice, and .github. lattice-dashboard is the canonical modern Vue dashboard; server images pin a specific dashboard commit through lattice-server/dashboard.ref.

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 published SDK baseline: latest lattice-sdk tag is v0.2.17; lattice-server consumes v0.2.17, and lattice-node-agent consumes v0.2.17. The workspace use list includes the local SDK checkout, so cross-repo development exercises the current model sources without relying on a stale version-specific replace.