Documentation

EdgeGuardian holds each device to a declarative desired state and ships your custom software to groups of devices. You upload a signed binary, freeze it into an immutable release, and roll it out to a group selected by device labels. Each device pulls, verifies, and installs it atomically — and rolls back on its own if the new version turns out unhealthy.

Everything here is driven by a small REST API. All requests are scoped to your organization; you only ever see and touch your own devices.

Automation authenticates with an organization API key, created in the dashboard under Settings → API keys. It needs at least the OPERATOR role to deploy. Send it as a bearer token on every request:

Authorization: Bearer <your-api-key>

(Interactive users in the dashboard use a Keycloak login instead — same endpoints, same org scoping.)

Shipping a workload to a fleet is four calls. The examples use $EG for your controller URL and $TOKEN for the API key.

1. Upload the artifact. Your binary, stored immutably and addressed by (name, version, architecture). The SHA-256 is computed for you; an Ed25519 signature is optional but verified on the device.

curl -X POST "$EG/api/v1/artifacts" \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=sensor-agent" -F "version=2.5.0" -F "architecture=arm64" \
  -F "file=@build/sensor-agent"

2. Create a release. A frozen desired-state spec that references the artifact. The controller injects a short-lived presigned download URL + hashes at push time so the device can fetch and verify it.

curl -X POST "$EG/api/v1/releases" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "v2.5.0",
    "spec": {
      "artifacts": [
        { "name": "sensor-agent", "version": "2.5.0",
          "exec": "sensor-agent", "service": "sensor-agent" }
      ],
      "services": [ { "name": "sensor-agent", "enabled": "true", "state": "running" } ],
      "health": {
        "intervalSeconds": 30,
        "checks": [
          { "name": "api", "type": "http",
            "target": "http://127.0.0.1:8080/healthz", "timeoutSeconds": 3 }
        ]
      }
    }
  }'

The health checks are what gate a canary rollout and trigger the device's automatic rollback.

3. Create a deployment group. A dynamic cohort selected by device labels — a device belongs whenever its labels match the selector.

curl -X POST "$EG/api/v1/deployment-groups" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "prod", "selector": { "env": "prod", "role": "gateway" } }'

# Preview exactly which devices match, before deploying:
curl "$EG/api/v1/deployment-groups/7/devices" -H "Authorization: Bearer $TOKEN"

4. Deploy. Roll the release out to the group with a strategy.

curl -X POST "$EG/api/v1/deployments" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "groupId": 7, "releaseId": 42, "strategy": "canary" }'

Watch it converge at GET /api/v1/deployments/{id}/targets, or open the Deployments page in the dashboard for the live wave-grid.

Two strategies, matched to a device fleet:

• forced — apply to every matching device at once, no health gate. Fast, no safety net. For emergencies or dev.
• canary — apply to a small lead wave first, wait for it to report healthy, then expand to the rest in gated waves. If the lead wave (or any later wave) fails the health gate, the rollout halts before reaching the rest of the fleet.

When a device receives a release it:

1. Downloads the artifact and verifies its SHA-256 + Ed25519 signature.
2. Installs it atomically into a versioned directory and restarts the service.
3. Runs your health checks.
4. If they fail within the bake window, it automatically rolls back to the previous version and reports the failure — so a bad release self-heals instead of taking the device down.

The handful you'll use most. All under /api/v1, all org-scoped.