Runners

Manage self-hosted runners that execute infrastructure scans in your own environment.

Base path: /api/runners

Runner routes are split into two categories:

• User-facing routes — require JWT/CLI token authentication
• Runner agent routes — require runner token via X-Runner-Token header

User-Facing Routes

List Runners

GET /api/runners/

Authentication: Bearer token required | Scope: runners:read

List all runners for the authenticated user.

Response

{
  "success": true,
  "data": [
    {
      "_id": "runner1",
      "name": "production-runner",
      "status": "online",
      "version": "1.2.0",
      "lastHeartbeat": "2025-06-15T10:30:00.000Z",
      "jobsCompleted": 156
    }
  ]
}

Example

curl -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/runners/

Create Runner

POST /api/runners/

Authentication: Bearer token required | Scope: runners:manage

Register a new self-hosted runner.

Request Body

Field	Type	Required	Description
name	string	Yes	Runner display name
labels	string[]	No	Runner labels for job routing

Response

{
  "success": true,
  "data": {
    "_id": "runner1",
    "name": "production-runner",
    "token": "rn_abc123...",
    "status": "offline"
  }
}

WARNING

The runner token is only returned once at creation time. Store it securely.

Get Runner

GET /api/runners/:runnerId

Authentication: Bearer token required | Scope: runners:read

Get details for a specific runner.

Path Parameters

Parameter	Type	Description
runnerId	string	Runner ID

Update Runner

PUT /api/runners/:runnerId

Authentication: Bearer token required | Scope: runners:manage

Update runner configuration.

Path Parameters

Parameter	Type	Description
runnerId	string	Runner ID

Request Body

Field	Type	Required	Description
name	string	No	New runner name
labels	string[]	No	Updated labels

Delete Runner

DELETE /api/runners/:runnerId

Authentication: Bearer token required | Scope: runners:manage

Delete a runner.

Path Parameters

Parameter	Type	Description
runnerId	string	Runner ID

Regenerate Token

POST /api/runners/:runnerId/regenerate-token

Authentication: Bearer token required | Scope: runners:manage | Rate limit: Strict (5/hour)

Regenerate the runner's authentication token. The old token is immediately invalidated.

Path Parameters

Parameter	Type	Description
runnerId	string	Runner ID

Mark Offline

POST /api/runners/:runnerId/mark-offline

Authentication: Bearer token required | Scope: runners:manage

Manually mark a runner as offline.

Get Setup Info

GET /api/runners/:runnerId/setup-info

Authentication: Bearer token required | Scope: runners:manage

Get setup information for the CLI, including the runner token.

Get Install Script

GET /api/runners/:runnerId/setup

Authentication: Runner token (via query param)

Download the runner installation script. No JWT required — runner token in the URL validates access.

Runner Agent Routes

These endpoints are used by the runner agent process itself (not by users).

Heartbeat

POST /api/runners/heartbeat

Authentication: X-Runner-Token header | Rate limit: Runner (120/min)

Send a heartbeat to report runner status.

Request Body

Field	Type	Required	Description
status	string	Yes	Runner status (online, busy)
version	string	No	Runner agent version
systemInfo	object	No	System metrics (CPU, memory, disk)

Example

curl -X POST https://api.controlinfra.com/api/runners/heartbeat \
  -H "X-Runner-Token: rn_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status": "online", "version": "1.2.0"}'

Poll for Jobs

POST /api/runners/jobs

Authentication: X-Runner-Token header | Rate limit: Runner (120/min)

Poll for pending scan jobs assigned to this runner.

Response

{
  "success": true,
  "data": {
    "job": {
      "_id": "job1",
      "type": "scan",
      "repositoryConfig": "abc123",
      "repositoryName": "org/terraform-infra",
      "branch": "main"
    }
  }
}

Update Job Status

POST /api/runners/jobs/status

Authentication: X-Runner-Token header | Rate limit: Runner (120/min)

Report job completion or failure.

Request Body

Field	Type	Required	Description
jobId	string	Yes	Job ID
status	string	Yes	Job status (running, completed, failed)
result	object	No	Job result data
error	string	No	Error message (if failed)