Pre-release documentation.
Commands may change. The binaries are named gridweaved, gridweave, gridweave-admin and gridweave-agent. GridWeave is under construction and not released: there is no download, no installer package and nothing is code-signed.
Start here
Quickstart
Start the system with
make dev-docker, sign in, enrol a local agent and run a first script. Needs Docker with Compose and GNU Make.Deployment
One host with PostgreSQL, TLS and systemd, containers and Compose, or Kubernetes with the Helm chart. First-install notes and honest limits.
Command-line reference
The subcommands and flags of
gridweaved,gridweave-admin,gridweaveandgridweave-agent, andreleasesign.Concepts
Tenants, device groups, roles and delegation, enrolment, signed commands, jobs, sessions, consent, recordings and tokens.
Which page do I need?
| I want to | Read | Status |
|---|---|---|
| Try GridWeave on my machine, enrol a device and run a script | Quickstart | Partial Run on a Mac; the web screens were not driven through end to end |
| Install the server on a Linux host as a service | Deployment: single host | Partial Run on Ubuntu 24.04 ARM64; not production ready |
| Run it in containers or on Kubernetes | Containers, Helm | Partial Evaluation; one single-node cluster |
| Enrol a real machine as a device | Enrol an agent | Partial Linux run; macOS dry run; Windows not verified |
| Look up a command or flag | Command-line reference | Current From the usage text of the code |
| Understand the ideas first | Concepts, Architecture, Security | Current |
Names you will meet
The product is called GridWeave. The binaries were renamed in feature 043; nothing was released under the earlier names, so there is no compatibility layer.
| Name | Earlier name | What it is |
|---|---|---|
gridweaved | nsd | The server |
gridweave | nsctl | The user command-line client |
gridweave-admin | nsadmin | The operator tool |
gridweave-agent | nsagent | The endpoint agent |
The agent’s service, unit, directories and local socket are all named gridweave-agent. What did not change: the NS_* configuration variables, NSAGENT_ENROLLMENT_TOKEN and the other upper-case NSCTL_* variables, the ns.* protocol packages and the ns_ database roles. The owner decides the prefix later. On Windows and macOS the new service names were never run (see below).
What was verified, and where
Every guide was written from commands run on real machines on 2026-11-13, and it says where it did not. The product has run in a small number of places.
| Where | What ran there | Not run there |
|---|---|---|
| An Apple-silicon Mac (macOS), Docker-compatible runtime | The development environment (host processes and Docker), enrolment of a foreground agent, the split-role Compose stack, the image builds | A cold build was not timed; the macOS LaunchDaemon ran as a dry run only, and its renamed property list was only checked with plutil |
| An Ubuntu 24.04.3 ARM64 virtual machine | The single-host deployment, gridweave-agent install as a systemd service (install, run and uninstall again after the rename), agent self-update with automatic rollback, backup, restore and a no-op upgrade | x86-64, other distributions, a certificate from a public authority, load |
| A single-node k3s 1.31 cluster in a container | The Helm chart: migration hook, all roles, first administrator, an agent | Ingress, autoscaling, network policies, more than one node, a real registry |
| A Windows 11 ARM64 virtual machine | The Windows agent's service, collectors and executors, before it became unreachable | The installer script, the terminal and the consent prompt were never run, and the renamed Windows service names were type-checked only |
CI is disabled, so the product's own local check set is the gate. Nothing is code-signed. The status page of the roadmap lists what is built, partial and not built.
More documentation
The product repository holds a project wiki with deeper pages: quickstart, single-host deployment, containers and Kubernetes, key management, settings and limits, personal access tokens, operations and a set of playbooks for AI coding agents that help an operator set up, configure and deploy. The repository is not public yet, so those pages are not linked here. The pages on this site are written from them and say what each claim rests on.
There is no download, installer or hosted trial yet, so no page documents one.