Agent registration and entitlements

An agent joins a studio by claiming a licence. The licence is a one-shot ticket: it says who the machine belongs to, and it is spent the moment the machine registers.

The two licence types

A licence carries its own type, and the type decides the ownership of the machine that presents it.

Where the machine physically sits makes no difference. A personal licence used on a bench in the lab still registers a personal machine — the person owns it, wherever it happens to be plugged in. The location field on a lab licence is a note for the humans, not a rule for the system.

The registration flow

1. A licence is issued

   A person signs in to the studio and applies for a personal licence in their Personal Center, or an administrator issues a lab licence. The studio creates a row in agent_licenses with status pending and returns a licence code.

2. The agent checks the code

   GET /api/agent/license?code=… answers with the licence's type and scope, so the operator can see whether the machine will be personal or lab before registering it.

3. The agent registers

   POST /api/agent/register presents the code plus a name. The studio validates the licence against its status and expiry, creates the agent in the scope the licence type dictates, and returns the agent's permanent identity: agentId, apiKey and agentSecret.

4. The agent authenticates on the socket

   The agent opens a Socket.IO connection to the studio and sends an auth request with agentId, agentSecret and protocolVersion. The studio answers with an auth response whose data holds agentId, name, capabilities and protocolVersion. A mismatch produces ok: false with the code AUTH_FAILED, after which the studio disconnects the socket.

The licence moves from pending to consumed when the agent claims it. A consumed licence never works again — presenting the same code a second time is refused.

Issuing a personal licence

Every signed-in person issues their own personal licences. In the studio, open Personal Center and use the Apply for a license action. The code appears once; copy it and enter it on the machine.

The same thing over HTTP:

curl -X POST http://studio.lab.internal:3000/api/licenses \
  -H 'Content-Type: application/json' \
  -H "Cookie: session=$SESSION" \
  -d '{"type":"personal"}'

{
  "success": true,
  "license": {
    "id": "0f2c9d1e-…",
    "code": "dk_l_…40 hex characters…",
    "type": "personal",
    "ownerUserId": "9a1c…",
    "location": null,
    "label": null,
    "status": "pending",
    "expiresAt": null,
    "createdAt": "2026-11-02T09:14:00.000Z"
  }
}

The licence belongs to the person who applied for it. Nobody else can see the code — a licence is the ticket, and only its owner and an administrator can read it.

Issuing a lab licence

Administrators issue lab licences for the shared benches from Admin → Licences. A lab licence carries a location and a label, and it belongs to the lab rather than to a person.

curl -X POST http://studio.lab.internal:3000/api/licenses \
  -H 'Content-Type: application/json' \
  -H "Cookie: session=$SESSION" \
  -d '{"type":"lab","location":"A-12","label":"Bench A"}'

Registering the machine

On the bench, open the agent's page at http://localhost:3001, fill in the form and submit. The form asks for the studio URL, the agent name and the licence code. The Check license button asks the studio what kind of licence it is and shows the answer before anything is registered.

The agent sends:

{
  "code": "dk_l_…40 hex characters…",
  "name": "bench-01",
  "studioUrl": "http://studio.lab.internal:3000",
  "workstation": { "hostname": "bench-01", "platform": "linux", "arch": "x64" },
  "capabilities": []
}

The studio answers:

{
  "success": true,
  "agentId": "6d1f…",
  "apiKey": "…32 alphanumeric characters…",
  "agentSecret": "…64 hex characters…",
  "licenseType": "personal",
  "scope": "personal",
  "ownerUserId": "9a1c…",
  "location": null,
  "reRegistered": false
}

The agent writes these to data/agent.json on the bench, and then opens the socket.

Entitlements

Two entitlements govern who may run on the install, and they belong to different keys.

The studio licence is checked when the install is set up and whenever an agent claims a seat. The agent licence is checked at registration: an unknown, revoked, expired or already-consumed licence is refused with 403. See Self-hosted deployment for the editions and their allowances.

Issue one licence per machine. A licence is claimed once, and a licence shared across a fleet makes revocation meaningless.

The credentials

A registration produces two credentials, and they are used in different places.

Neither is ever sent in a header. There is no Authorization header, no X-API-Key header and no bearer token anywhere in the product; the credentials travel in request bodies and socket payloads. The agent never calls POST /api/agent/auth in normal operation — the endpoint exists for scripted use and returns the agent's id, name and capabilities. The socket handshake checks only the agentSecret: an agent that sends a valid agentId with a wrong secret gets an AUTH_FAILED answer and is disconnected.

Revoking access

To withdraw a licence, revoke it:

curl -X POST http://studio.lab.internal:3000/api/licenses/<id>/revoke

The licence status becomes revoked. The next POST /api/agent/register with that code is refused with 403. The owner of a licence may revoke their own; an administrator may revoke any.

A licence that has already been consumed cannot be revoked — the machine is on the ledger and points at that licence. To take that machine out of service, delete the agent itself with DELETE /api/admin/agents/<id>.

Troubleshooting registration

More on connectivity in Agent offline and in Network requirements.

Related pages

• Self-hosted deployment — running the studio.
• Network requirements — ports and outbound access.
• Personal Center — issuing and revoking your own licences.
• The agent pool — managing a fleet of registered agents.
• Socket protocol — the message envelope and handshake.
• REST API reference — every endpoint.