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.