Skip to Content
Puppi

Workers API

Tokens for a pool, and the workers connected to it.

A Puppi worker dials the engine and takes attempts for a remote environment. You run puppi worker start or the Puppi image. Puppi does not support a client you write for the attempt claim routes. These routes create a token and list the workers that are connected. They use the API bearer token. The socket uses a worker token.

Tokens

GET /api/v1/worker-tokens lists the caller’s tokens. A row has id, name, last_used_at, and inserted_at. The plaintext is not in the list.

POST /api/v1/worker-tokens creates one. The body is {"name":"droplet-1"}. 201 returns the same fields plus token, once.

curl -X POST \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"droplet-1"}' \
  "$PUPPI_ENGINE_URL/api/v1/worker-tokens"

DELETE /api/v1/worker-tokens/:id revokes the token and closes the sockets that presented it. Another pool’s id is 404. The response is {"data": {"id": "<id>"}}.

Connected workers

GET /api/v1/workers returns the pool as it is connected now.

curl -s \
  -H "Authorization: Bearer <api-key>" \
  "$PUPPI_ENGINE_URL/api/v1/workers"
{
  "data": {
    "queue_depth": 0,
    "workers": [
      {
        "id": "droplet-1",
        "version": "0.4",
        "residency": "strict",
        "free_slots": 4,
        "attempts": [],
        "secrets": ["warehouse_password"],
        "trusted_keys": ["<sha256 hex>"]
      }
    ]
  }
}

id is the configured worker id and defaults to the hostname. It is not the token name. secrets lists secret names the worker reported. trusted_keys are SHA-256 fingerprints of the Ed25519 public keys it trusts. puppi worker list compares secrets with the worker-held names declared on your environments and adds the ones that are missing.

The socket

A worker dials GET /api/v1/workers/socket with Authorization: Bearer <worker token> and asks for a WebSocket upgrade. An incompatible image tag is 403 with {"error": "incompatible worker; pull <image>"}. The image is private. Pull it with a registry credential before the worker can connect. See Workers.