Quickstart

Before you start

You will start the whole system on one machine with Docker, sign in to the console, enrol a Linux agent that runs in a container, and run a first script on it. Every step below comes from the product's own development environment (deploy/container/compose.dev.yaml, its dev-init.sh and the Makefile).

• Docker with Compose. The image builds use docker buildx.
• GNU Make. The macOS version is enough.
• A checkout of the GridWeave source repository. There is no download or installer yet, so the commands run from the root of a checkout.
• Free ports 8080 and 8443 (console and API, and agents). The optional profiles also use 5173 and 8081. Change them with GW_DEV_HTTP_PORT, GW_DEV_AGENT_PORT, GW_DEV_WEBDEV_PORT and GW_DEV_KEYCLOAK_PORT.
• Chrome or Firefox. Sign-in cookies need HTTPS or localhost, and Safari cannot sign in over plain HTTP.

1. Start the system

One command builds the server and agent images, starts PostgreSQL, applies the migrations, creates the certificate authority and the first administrator, and starts gridweaved all-in-one with the console embedded.

make dev-docker

It ends by printing a summary that begins with dev: ready. The lines look like this (the pin is a 64-digit fingerprint of the installation's root certificate):

dev: ready
  console    http://localhost:8080
  sign in    admin / admin-dev-only-password
  API        http://localhost:8080/api/v1/system/info
  agents     https://localhost:8443 (mutual TLS; root pin <64 hex digits>)
  agent      docker compose -f deploy/container/compose.dev.yaml --profile agent up -d
  stop       make dev-docker-down   (the database volume is kept; docker compose down -v deletes it)

The summary also lists the optional web-dev and sso profiles. Check that the server is ready:

curl -fsS http://localhost:8080/readyz
curl -fsS http://localhost:8080/api/v1/system/info

The first answers {"failed":[],"status":"ready"} and the second names the mode, "mode":"all-in-one".

How long it takes. The first run builds two images and pulls PostgreSQL, so it depends on your network and machine; no figure is claimed for it. On a warm start (images and caches present, empty volumes) the summary appeared after 6 seconds in the product's own run, on non-default ports.

2. Sign in

Open http://localhost:8080 and sign in as admin with the password admin-dev-only-password. These credentials are public and exist only in the development environment.

The web application was tested against stubs and a canned API, and the console routes named on this page come from its screens, not from a recorded click-through against this exact setup. Expect rough edges and tell us what you find.

3. Enrol a local agent

Start the agent profile. A one-shot step writes the agent's configuration, copies the root certificate, and asks the server for a single-use enrolment token in a device group named Development. Then a Linux agent container enrols with that token and stays connected.

docker compose -f deploy/container/compose.dev.yaml --profile agent up -d

Open Devices in the console. The new device appears within seconds and shows as online. To follow what the agent does, read its log:

docker compose -f deploy/container/compose.dev.yaml --profile agent logs agent

4. Run a first script

In the console: Devices, tick the device, choose Run script..., pick sh as the interpreter, enter the script below and run it. The job view shows each device's exit code and output.

echo hello; uname -sm; id -un

You should see exit code 0, the line hello, the kernel name and architecture of your Docker host (a Linux kernel), and the user the agent runs as. Behind the button, the server signs the command, the agent checks the signature, the device, the tenant, the time and its permissions itself, and only then runs the script. The script text is written to the audit log. See signed commands and jobs.

The same from the command line

gridweave is the user command-line client. It needs Go to build and a personal access token. Build it, then create a token in the console under Account. The credential starts with gwp_ and is shown once.

make build-server

make build-server writes bin/gridweaved, bin/gridweave-admin and bin/gridweave. Put the token in a file only you can read. It is never taken from a command-line flag.

umask 077; read -rs T; printf %s "$T" > token.txt; unset T
bin/gridweave login --server http://localhost:8080 --token-file token.txt
bin/gridweave devices list
bin/gridweave run DEVICE -c 'echo hello; uname -sm; id -un'

DEVICE is a device id or its exact name from the list. Plain http is accepted only for a loopback address. gridweave run waits for the result and exits with the script's own exit code when you name one device. All commands and flags are in the command-line reference.

5. Stop, or start again

make dev-docker-down

This stops the containers and keeps the database volume, so the next make dev-docker finds the administrator, the certificate authority and the enrolled device. To delete the data as well, run docker compose with down -v against deploy/container/compose.dev.yaml, naming the same profiles the Makefile names. make dev, the host-process alternative for fast iteration, uses the same ports: run one of the two.

Optional profiles

Troubleshooting

Where to go next

• Concepts: what tenants, device groups, roles, jobs, sessions and consent mean.
• Deployment: run the server on a host, in containers or on Kubernetes, and enrol a real machine.
• Command-line reference: every subcommand and flag of gridweave-admin, gridweave and gridweave-agent.
• Roadmap and status: what is built, partial and not built.