Install the droplet agent (.deb package)

Most fleets run the purpose-built SPEKTRA Edge OS image. If instead you want to bring an existing Debian/Ubuntu Linux under management, you can install the droplet agent from a .deb package. The machine then joins your project and runs managed workloads, while you keep your own operating system.

This page walks you through the whole flow: install the package, create a provisioning policy and a service account, grant the service account a role, download its key, convert the key into a project_config.json, and place that file where the agent reads it.

Prerequisites

• Architecture: x86-64 (amd64) or ARM64 (arm64). These match the supported platforms for the OS image.
• Operating system: a Debian-based Linux (Debian or Ubuntu) with systemd and root/sudo access.
• Package dependency: wireguard (pulled in as a dependency of the package).
• Container runtime: Docker with Docker Compose, used by the default pod driver to run workloads.
• Platform access: the SPEKTRA Edge dashboard and an active project, with permission to manage provisioning policies, service accounts, service account keys, and role bindings.
• Local tools: jq (used to build project_config.json).

Default-enabled functions

The packaged systemd unit starts the agent with the pod driver and with OS management disabled:

droplet run --driver compose --disable-os-management \
  --device-service-account-file /etc/droplet/device_config.json \
  --project-service-account-file /etc/droplet/project_config.json \
  --use-journald-compatible-log

As a result, on a .deb install:

If you want to enable additional capabilities, edit the ExecStart line in /lib/systemd/system/droplet.service (each capability has its own --disable-* flag) and reload with sudo systemctl daemon-reload.

Not available with the package install

The .deb agent runs on your operating system, so the platform features that are properties of SPEKTRA Edge OS itself are not available. You remain responsible for the host OS. In particular, the following are not supported:

What you do get is device onboarding, remote workload/pod management, and telemetry — see Default-enabled functions.

Install the package

Copy the .deb matching your architecture onto the host and install it:

sudo dpkg -i droplet_<version>_<arch>.deb
# resolve dependencies (e.g. wireguard) if dpkg reports any
sudo apt-get install -f

The package:

• installs the agent binary at /usr/bin/droplet,
• installs the service unit at /lib/systemd/system/droplet.service,
• creates the working directory /var/lib/droplet,
• enables and starts the droplet service automatically.

At this point the service is running but has no identity yet. It will keep retrying until you supply project_config.json, which you provide in the next section.

Create the agent’s identity (project_config.json)

The agent onboards using a project-scoped project_config.json. There are two ways to obtain it — pick one:

• Reuse from an existing device (fastest). If you already have a device that onboards against the same project and provisioning policy, its project_config.json is a shared credential you can copy as-is. Grab it from that device — /etc/droplet/project_config.json on a package install, or /isodevice/config/project_config.json on SPEKTRA Edge OS — and skip straight to Install the identity file. See Reuse across devices for why this is safe.
• Create from scratch. If this is a new project or you want a dedicated credential, follow the numbered steps below to create a provisioning policy, a service account with the right role, and a key, then convert it.

The steps below cover the create-from-scratch path.

Step 1 — Create a provisioning policy

A provisioning policy lets a device self-register into your project. Create one in the dashboard and choose a mode:

The policy also defines the role bound to each newly created device identity (default: services/devices.edgelq.com/roles/v1-device-agent). See provisioning concepts for background.

Step 2 — Create a service account

In the dashboard, open your project and create a Service Account (for example fleet-provisioner). This is the shared, project-scoped identity that devices will present in order to self-provision.

Step 3 — Assign the provisioning role and attach it to the policy

For the service account to be allowed to provision devices, it needs the Device provisioner role:

services/devices.edgelq.com/roles/v1-device-provisioner

This role grants the provisionDeviceViaPolicy and requestProvisioningApproval permissions (scoped by project, region, service account, and provisioning policy).

1. Bind the Device provisioner role to the service account from Step 3.
2. Associate the service account with the provisioning policy from Step 2, so devices using this account are matched to that policy.

Step 4 — Create and download a service account key

Open the service account → Service Account Keys → Create. On creation the dashboard downloads a JSON key file (shown only once). Save it as service-account-key.json. It looks like:

{
  "type": "service_account_key",
  "client_email": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
  "private_key_id": "projects/.../serviceAccountKeys/<key>",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

Step 5 — Convert the key to project_config.json

The agent expects the key wrapped in a config with a droplet service set. Build it from the downloaded key, setting defaultDomain to the controller endpoint your device connects to (for example apis.edgelq.com, or your dev/staging domain):

jq --arg domain "apis.edgelq.com" '{
  accounts: [ { serviceAccount: (. + {type: "service_account"}) } ],
  activeAccountName: .client_email,
  serviceSets: [ { name: "droplet", defaultDomain: $domain } ],
  activeServiceSetName: "droplet"
}' service-account-key.json > project_config.json

The result:

{
  "accounts": [
    {
      "serviceAccount": {
        "type": "service_account",
        "client_email": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
        "private_key_id": "projects/.../serviceAccountKeys/<key>",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
      }
    }
  ],
  "activeAccountName": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
  "serviceSets": [ { "name": "droplet", "defaultDomain": "apis.edgelq.com" } ],
  "activeServiceSetName": "droplet"
}

Notes:

• activeAccountName must equal the client_email.
• Keep private_key on one line with its \n escapes intact (valid JSON).
• defaultDomain is the controller endpoint the agent connects to — not the IAM host inside the email.

Install the identity file

Whether you reused an existing project_config.json or created one above, install it where the packaged service reads it, and lock down its permissions (it contains a private key):

sudo install -o root -g root -m 600 project_config.json /etc/droplet/project_config.json
sudo systemctl restart droplet

Reuse across devices

project_config.json is a shared, project-scoped credential — it is not tied to any single machine. That means:

• You can reuse an existing project_config.json taken from another device that already onboards against the same project and policy.
• You can copy the same file to many devices. Each device presents this shared identity only to self-provision; on success it receives its own, device-scoped identity (/etc/droplet/device_config.json) and uses that from then on.

This is why a single install image or a single copied config can serve an entire fleet, with no per-device credential preparation.

Verify

1. Watch the agent logs:

   journalctl -u droplet -f
   

   The agent should load the project config and attempt self-provisioning.

2. In the dashboard, under your project:

   • Unattended: a new Device appears automatically.
   • Manual approval: a pending provisioning request appears — approve it.

3. Once provisioned, the device shows as Online and reports its OS version, hardware, and network details.

If the device does not come online, check the connectivity requirements and the troubleshooting playbooks.