A single Go server binary that runs as many roles, a Rust agent on each device, a React web app, and three places that hold state: PostgreSQL, a NATS bus and object storage. This page says what is built and what is not.
Under construction. Not released.
The shape of it
The server gridweaved takes the role to run as its first argument. A service process holds connections and caches only. State lives in PostgreSQL, on the bus and in object storage, so a role can run as many copies as needed.
gridweave call the api role over HTTPS and join terminal and files sessions on the relay role over WebSocket. The agent connects to the agent-gateway over mutual TLS and to the relay over WebSocket. The amt role also accepts connections from Intel AMT firmware. The bridge role is not implemented.The binaries are gridweaved (the server), gridweave-admin (the operator tool), gridweave (the user command line) and gridweave-agent (the endpoint agent). They were renamed in feature 043 from nsd, nsadmin, nsctl and nsagent. The NS_* configuration variables, the ns.* protocol packages and the ns_ database roles kept their names.
Every change a user makes is written in one PostgreSQL transaction together with an outbox row. A worker then appends the audit entry and publishes the event to the bus, at least once and with a stable event id, and the event reaches browsers over a WebSocket if the tenant, topic and permission allow it. The audit entry is therefore recorded with the change, not as an afterthought.
Server
gridweaved.The Go server is one module and one binary. The first argument selects the role, in a separate process or all in one. gridweave-admin is the operator tool and is not a service.
| Role | What it does | Status |
|---|---|---|
api | The HTTP API under /api/v1, the event stream, authentication and authorisation. Needs the database, the bus and a key store. | Built |
agent-gateway | The agent listener: enrolment, mutual TLS, presence, reports and forwarding of commands. Holds no authoritative state, so several gateway nodes behave as one. | Built |
relay | The data plane of terminal and files sessions: WebSocket legs, pairing, flow control, revocation. Terminal and files only; the other protocols the contract names are defined and refused. Taps terminal sessions into a recording when policy says so, and admits guest links. | Built |
worker | The outbox relay, scheduled jobs and the janitor for sessions a dead relay left open. | Built |
web | Serves the web application assets. They are embedded in the binary only by the release build. | Built |
amt | Optional. Intel AMT: a listener for connections from the firmware, management over WS-Management, and device operations over the bus. Off unless enabled in the configuration. | Simulator only |
all-in-one | Every implemented role in one process, with an embedded bus and a local object store. Used for development and small installs. | Built |
bridge | Protocol bridges. The role is registered and exits with a message that it is not implemented. | Not built |
Each role opens only the keys it needs. For example the gateway never opens the Command CA key that signs commands, so a compromised gateway cannot sign one. Configuration is one YAML file plus environment overrides, checked against a schema; unknown keys are refused.
Device
gridweave-agent.A Rust program that runs as a service on each device. It enrols once with a token, then keeps one long-lived connection to the gateway.
A systemd unit on Linux, a LaunchDaemon on macOS and a Windows service. Proven on Ubuntu 24.04 ARM64. On macOS it ran as a foreground process and the service install was only a dry run. The Windows parts written most recently have never been run.
TLS 1.3 with the platform root as the only trust anchor, HTTP/2, one stream, a heartbeat every 15 seconds by default and reconnects with backoff. The certificate is renewed at two thirds of its life. The key is a protected file, not in a TPM or the Keychain.
Per-system collectors report device state, network and inventory to the server. There are separate collectors for Linux, macOS and Windows.
Commands run only after the agent has verified them. The executors for Unix and for Windows are separate code, and only a verified command can reach them: the compiler refuses any other path.
A session offer is one more signed command. The agent checks it and the grant inside it, opens its leg to the relay, asks the person at the device when policy says so, and serves a terminal or a files session.
The agent acts on exactly six server messages on its stream and none of them carries code to run. Updates arrive by a separate path (next card) and are signed manifests checked against keys built into the agent; today those are development keys.
An installed agent asks the gateway for an update every 15 minutes by default, but only learns a version and a reason, never an address. It downloads from the server it enrolled with, verifies the signed manifest and the artifact, swaps its binary, and exits so that the service manager starts the new one. If the new build is not connected and stable within its window, the previous build is restored, either by the new build or by a watchdog timer that the previous binary armed first. Proven on Linux under systemd; macOS launchd and Windows are unverified.
The gateway’s update endpoints answer from a rollout engine: rings over a stable hash of the device id, a weekly window, a concurrency limit, per-group and per-device policies and a health gate that halts the rollout when too many devices fail or roll back. Every refusal is audited. Managed in the console under Updates, with the agent.rollout.manage permission.
The service, unit, directories and local socket are all named gridweave-agent: for example the systemd unit gridweave-agent.service, /etc/gridweave-agent/agent.toml and /run/gridweave-agent/gridweave-agent.sock. A local socket lets helper applications talk to the agent, with peer-credential access control. The Windows and macOS names were not run after the rename.
Not built: proxy support (the agent connects directly), a WebSocket fallback, and a helper application for consent prompts on Linux and macOS desktops.
Web, data and keys
React 18 with TypeScript and Vite. Its API client is generated from the OpenAPI contract, so the browser and the server cannot drift apart unseen. It was redesigned with Tailwind CSS and shadcn/ui and is checked by a layout check at three widths in both themes. It includes Terminal and Files tabs that use the relay, a recordings player, a sharing tab for guest links and an Updates area for releases and rollouts. Folder browsing in Files is not built.
The system of record. Every tenant table carries a tenant id and a row-level security policy that is forced, so the database enforces isolation and not only the application. A test discovers every such table and checks that one tenant cannot read, move, insert or delete another's rows.
Presence (a key per device whose lease any frame from the agent renews, three heartbeat intervals and at least 45 seconds), rate limits and single-use grant records live in JetStream buckets. Commands travel as request and reply, and events as publish and subscribe, on subjects prefixed by tenant. all-in-one embeds the bus; split roles need an external server.
An S3-compatible API or local disk, behind one gatekeeper that scopes every key to a tenant. The first users are the agent release store and terminal session recordings. The S3 driver was checked only against SeaweedFS and local TLS test servers.
One interface for every private key and wrapped secret, with three drivers: plain files (the default, for development only), AES-256-GCM encrypted files, and OpenBao Transit for production. The production driver is not the default, and its chart path was rendered but not run against a real OpenBao.
PostgreSQL stores references to keys and wrapped values, never a private key. Password hashes, TOTP secrets and identity-provider secrets are wrapped by the key store.
Contracts first
Three machine-readable contracts are the only place an interface is defined. A contract change lands before or with the code that uses it, and clients are generated, never written by hand in parallel.
| Contract | Describes | Generated into |
|---|---|---|
| OpenAPI 3.1 | The HTTP API under /api/v1: 150 operations at the time of writing. | The Go server interface and the TypeScript client types of the web app. |
| AsyncAPI 3.0 | The event stream a client opens over WebSocket, and the list of event types. | Nothing; a check compares it with the events the server emits. |
| Protobuf | The agent protocol, relay grants, and the relay framing, control messages and credit. | Go types for the server; the agent compiles the same files at build time. |
Path of a command
An operator runs a script on up to 500 devices. Each device receives its own signed envelope and checks it before acting.
Windows executors were verified on one virtual machine that later became unreachable; the effect of shutdown, reboot and sleep on Windows was left out of testing on purpose.
Path of a remote session
A terminal or files session joins a client and an agent through a relay. Each side presents a signed, single-use grant.
Remote desktop on the relay is not built. Terminal and files are the only protocols opened, and the real agent has been exercised through the relay by one end-to-end test on macOS. Recording and guest sharing exist for terminal sessions only, and were tried with fake agent legs and the real relay, not a real agent or browser; the agent shows no notice of recording or of a guest yet.
Deployment shapes
None of these is a production deployment. The product says so for each one.
gridweaved all-in-one runs every implemented role in one process with an embedded bus and a local object store. It needs PostgreSQL.
All-in-one under systemd with PostgreSQL and TLS. Reference files are in the product. It was performed on one Ubuntu virtual machine and is not production ready.
The roles run as separate containers behind one origin, with an external NATS server that has JetStream. A split deployment needs a shared key directory with the file key drivers, or one token per role with OpenBao.
A Helm chart with a Deployment per role. It was installed on one single-node k3s cluster only. The ingress, autoscaling and network policies were not run on a cluster. It is for evaluation.
A server image with every role, built as static binaries and run as an unprivileged user, and a Linux agent image. Both build for arm64 and amd64, but nothing is signed or published, and the amd64 builds were not run.
make dev starts PostgreSQL, Keycloak, a certificate authority, an administrator and the server. make dev-docker runs the same inside containers, and builds and tests can also run in a builder container.
Scale
One load test on one machine. These numbers describe that machine. They are not a result for the reference hardware and they do not show that any scale target is met.
One host, shared with other work.
The test ran on an Apple M4 Max with 128 GB, in use by other work during every run (load average 14 to 19 for the main run). The load generator, the server and a PostgreSQL container with two virtual CPUs shared that machine. Nothing ran on Linux, on x86-64 or on more than one gateway process, and no figure was repeated.
| Measure | Result |
|---|---|
| Agents held | 10,000 of 10,000 connected, with no error class in the steady state |
| Command from the API accepting the job to the agent holding it | 95th percentile 198 ms, with 50 commands a second |
| Device seen online after it connects | 95th percentile 357 ms during the ramp |
| Server memory | About 1.45 GB resident, roughly 137 KB and 7 goroutines per connected agent |
| Server CPU while holding | About a quarter of one core, median |
| All 10,000 cut and reconnecting | 99% back in 56.8 s with the default database pool of 16, and in 19.2 s with a pool of 64, under very high host load (one sample each) |