Connected-Runtime Enrollment

Enroll external runtimes via the enrollment API, manage credentials, and monitor health.

What enrollment provides#

Enrollment registers an external runtime with a workspace so it can participate in the governed control plane — reporting heartbeat, sessions, events, evidence, and telemetry.

Create an enrollment#

POST /api/v1/workspaces/{id}/enrollments with:

Field	Description
`runtimeName`	Human-readable name for the runtime
`providerKind`	Runtime provider (e.g., github, gitlab, custom)

The response includes:

enrollment: durable record with runtime ID
runtimeCredential: plaintext credential (shown once, stored as hash)
connectCommand: ready-to-run bootstrap command
sdkEnrollment: full SDK descriptor for programmatic setup

Credential security#

Credentials are generated using library crypto (generateApiKey)
Only the hash is stored in the database
The plaintext is returned once at enrollment time
Rotate by creating a new enrollment if compromised

List enrollments#

GET /api/v1/workspaces/{id}/enrollments returns all enrolled runtimes for the workspace. Credentials are not included in list responses.

Health monitoring#

Enrolled runtimes that haven't connected yet appear as "inactive" / "Pending connection" in the external agents inventory. Once they send their first heartbeat, health status transitions to connected/stale/dormant based on heartbeat freshness.

Access control#

All enrollment endpoints require workspace membership via verifyWorkspaceAccess. Enrollment records are workspace-scoped with RLS policies enforcing isolation.