Build hosts and lab hosts
48 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.
API reference · Authentication · Errors
Endpoints
GET /api/v1/orgs/{orgID}/build/device-policies
List device policies
- Permission
workspaces:admin- Path parameters
orgID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
PUT /api/v1/orgs/{orgID}/build/device-policies/{class}
Replace one device policy
- Permission
workspaces:admin- Path parameters
orgID,class- Request body
- object
- Response
- 200: DevicePolicy
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 415:content_type; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/devices
List devices
- Permission
workspaces:create- Path parameters
orgID- Query parameters
class,host_id- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/lab-hosts
List lab hosts
- Permission
workspaces:create- Path parameters
orgID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}
Get one lab host
- Permission
workspaces:create- Path parameters
orgID,hostID- Response
- 200: LabHost
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
PATCH /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}
Update one lab host
- Permission
workspaces:admin- Path parameters
orgID,hostID- Request body
- LabHostPatch
- Response
- 200: LabHost
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 415:content_type; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/devices
List the devices of a lab host
- Permission
workspaces:create- Path parameters
orgID,hostID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/release-claims
Handles POST .../lab-hosts/{hostID}/release-claims (workspaces:admin, {"reason"}): releases the device claims a revoked host keeps until it confirms its teardown.
POST /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/revoke
Revoke a lab host
GET /api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens
List enrolment tokens
- Permission
workspaces:admin- Path parameters
orgID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens
Create an enrolment token
- Permission
workspaces:admin- Path parameters
orgID- Request body
- TokenRequest
- Response
- 201: CreatedToken
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 415:content_type; 503:policy_unavailable,unavailable
DELETE /api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens/{tokenID}
Delete one enrolment token
- Permission
workspaces:admin- Path parameters
orgID,tokenID- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/leases
List leases
- Permission
workspaces:create- Path parameters
orgID- Query parameters
limit,scope,state- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}
Get one lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Response
- 200: Lease
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts
List the artifacts of a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts
Create an artifact for a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Query parameters
name,run_id- Response
- 201: Artifact
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}
Get one artifact
- Permission
workspaces:create- Path parameters
orgID,leaseID,artifactID- Response
- 200: Artifact
- Errors
- 404:
not_found
DELETE /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}
Delete one artifact
- Permission
workspaces:create- Path parameters
orgID,leaseID,artifactID- Errors
- 404:
not_found
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}/content
Content of an artifact
- Permission
workspaces:create- Path parameters
orgID,leaseID,artifactID- Errors
- 404:
not_found
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/caches
List the caches of a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
PUT /api/v1/orgs/{orgID}/build/leases/{leaseID}/caches/{cacheName}/entries
Set the entries of a cach
- Permission
workspaces:create- Path parameters
orgID,leaseID,cacheName- Query parameters
key- Response
- 201: value
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/caches/{cacheName}/restore
Restore of a cach
- Permission
workspaces:create- Path parameters
orgID,leaseID,cacheName- Query parameters
key- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/kill
Kill a lease
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/release
Release a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Response
- 200: Lease
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/renew
Renew a lease
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs
List the runs of a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs
Create a run for a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Request body
- RunRequest
- Response
- 201: Run
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 415:content_type; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}
Get one run
- Permission
workspaces:create- Path parameters
orgID,leaseID,runID- Response
- 200: Run
- Errors
- 404:
not_found
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/complete
Complete a run
- Permission
workspaces:create- Path parameters
orgID,leaseID,runID- Request body
- CompleteRequest
- Response
- 200: Run
- Errors
- 400:
invalid_json; 404:not_found; 415:content_type
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/log
Log of a run
- Permission
workspaces:create- Path parameters
orgID,leaseID,runID- Errors
- 404:
not_found
PUT /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/log
Set the log of a run
- Permission
workspaces:create- Path parameters
orgID,leaseID,runID- Errors
- 400:
invalid_request; 404:not_found; 415:content_type
GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/ssh
An SSH connection to a lab lease's host as binary WebSocket messages, for the holder in their own session while the lease is active and ready and the kill switch is off. The host must hold its relay connection to this replica (503 host_not_connected otherwise). The open and the end are audited (build.lease.ssh_relay); the caller's session, permission and the lease are checked again while the connection lasts.
- Permission
workspaces:create- Path parameters
orgID,leaseID- Errors
- 400:
invalid_request; 401:session_required,unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/ssh/certificate
Create a certificate
- Permission
workspaces:create- Path parameters
orgID,leaseID- Request body
- object
- Response
- 200: CertificateResult
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 415:content_type; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/sync
Sync a lease
- Permission
workspaces:create- Path parameters
orgID,leaseID- Request body
- SyncRequest
- Response
- 200: SyncPlan
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 415:content_type; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/login-wipes
Answers the organization's owed login wipes to an administrator (audited).
- Permission
workspaces:admin- Path parameters
orgID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/pools
List pools
- Permission
workspaces:create- Path parameters
orgID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/pools
Create a pool
GET /api/v1/orgs/{orgID}/build/pools/{poolID}
Get one pool
- Permission
workspaces:create- Path parameters
orgID,poolID- Response
- 200: Pool
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
PATCH /api/v1/orgs/{orgID}/build/pools/{poolID}
Update one pool
- Permission
workspaces:admin- Path parameters
orgID,poolID- Response
- 200: Pool
- Errors
- 400:
invalid_json,invalid_request,step_up_separately; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 415:content_type; 503:policy_unavailable,step_up_unavailable,unavailable
DELETE /api/v1/orgs/{orgID}/build/pools/{poolID}
Delete one pool
- Permission
workspaces:admin- Path parameters
orgID,poolID- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/pools/{poolID}/caches
List the caches of a pool
- Permission
workspaces:admin- Path parameters
orgID,poolID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
DELETE /api/v1/orgs/{orgID}/build/pools/{poolID}/caches/{cacheName}
Delete one cach
- Permission
workspaces:admin- Path parameters
orgID,poolID,cacheName- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/pools/{poolID}/engines
List the engines of a pool
- Permission
workspaces:admin- Path parameters
orgID,poolID- Response
- 200: PoolEngines
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:policy_unavailable,unavailable
POST /api/v1/orgs/{orgID}/build/pools/{poolID}/leases
Create a lease for a pool
- Permission
workspaces:create- Path parameters
orgID,poolID- Request body
- LeaseRequest
- Response
- 201: Lease
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 415:content_type; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/quotas
List quotas
- Permission
workspaces:admin- Path parameters
orgID- Response
- 200: Quotas
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
PUT /api/v1/orgs/{orgID}/build/quotas
Set quotas
GET /api/v1/orgs/{orgID}/build/task-engines
List task engines
- Permission
workspaces:admin- Path parameters
orgID- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
GET /api/v1/orgs/{orgID}/build/usage
List usage
- Permission
workspaces:create- Path parameters
orgID- Query parameters
scope- Response
- 200: Usage
- Errors
- 400:
invalid_request; 401:unauthorized; 403:forbidden,person_required; 503:policy_unavailable,unavailable
Objects
object
| Field | Type | Description |
|---|---|---|
reason | string |
object
| Field | Type | Description |
|---|---|---|
reason | string |
object
| Field | Type | Description |
|---|---|---|
reason | string |
object
| Field | Type | Description |
|---|---|---|
ttl_seconds | integer |
object
| Field | Type | Description |
|---|---|---|
public_key | string |
object
| Field | Type | Description |
|---|---|---|
access | Access | |
requires_approval | boolean | |
approver_group_id optional | uuid |
object
| Field | Type | Description |
|---|---|---|
max_active_leases | integer | |
max_active_vcpus | integer | |
max_active_leases_per_person | integer | |
max_lease_hours_per_person_month | integer |
Access
Access says who may lease from a pool: the people, and (M3) the agents that may act for them.
| Field | Type | Description |
|---|---|---|
all_members | boolean | |
user_ids | array of uuid | |
group_ids | array of uuid | |
agents | AgentAccess | The pool's agent policy; its zero value (and a pool stored before M3) admits no agent. |
AgentAccess
AgentAccess says which agents may lease from a pool for the people its access policy admits.
| Field | Type | Description |
|---|---|---|
mode | string | None (default), listed or all. |
agent_ids | array of uuid | |
secrets | boolean | Secrets lets a lease taken by an agent receive the pool's secrets. |
Artifact
A build artifact of a lease.
| Field | Type | Description |
|---|---|---|
id | uuid | |
lease_id | uuid | |
run_id optional | uuid | |
name | string | |
size_bytes | integer | |
sha256 | string | |
created_by | uuid | |
acting_agent_id optional | uuid | |
created_at | timestamp | |
expires_at | timestamp |
CacheVolume
One cache of a pool: entries kept as objects, restored and saved by lease holders through the lease routes. It is not a volume mounted on the host: the server could not enforce one.
| Field | Type | Description |
|---|---|---|
name | string | |
scope | string | |
max_bytes | integer | |
total_max_bytes | integer | The cache's total over every holder: in a holder-scope cache max_bytes is each holder's own budget; in a pool-scope cache it is max_bytes. |
ttl_days | integer | |
agents | string |
CertificateResult
A certificate for a lease's host.
| Field | Type | Description |
|---|---|---|
certificate | string | |
serial | string | |
key_id | string | |
principals | array of string | |
valid_after | timestamp | |
valid_before | timestamp | |
ssh | SSHTarget |
CompleteRequest
CompleteRequest reports a run's outcome.
| Field | Type | Description |
|---|---|---|
exit_code optional | integer | |
duration_ms optional | integer |
CreatedToken
A new enrolment token; Token is shown once.
| Field | Type | Description |
|---|---|---|
id | uuid | |
token | string | |
name | string | |
expires_at | timestamp |
DevicePolicy
Who may claim a device class.
| Field | Type | Description |
|---|---|---|
class | string | |
access | Access | |
requires_approval | boolean | |
approver_group_id optional | uuid | The Directory group whose members may decide this class's lease approvals, besides holders of approvals:approve. |
updated_by optional | uuid | |
updated_at | timestamp |
DeviceRequest
One device a lab lease claims: by device_id or by class, not both.
| Field | Type | Description |
|---|---|---|
device_id optional | uuid | |
class optional | string |
Egress
The pool's egress policy.
| Field | Type | Description |
|---|---|---|
mode | string |
Holder
Who holds a lease.
| Field | Type | Description |
|---|---|---|
type | string | |
id | uuid |
Host
The state of a lease's host.
| Field | Type | Description |
|---|---|---|
status | string | |
ssh_user optional | string | |
ready | boolean |
LabHost
A lab host.
| Field | Type | Description |
|---|---|---|
id | uuid | |
org_id | uuid | |
name | string | |
status | string | |
labels | object of string | |
pool_ids | array of uuid | |
max_leases | integer | |
disabled | boolean | |
hostname | string | |
os | string | |
arch | string | |
os_version | string | The OS release the host last reported (macOS product version, Linux kernel release); empty until an agent that reports it heartbeats. |
version | string | |
health | string | |
ssh_host_key | string | The host's SSH host key as it last reported it (ssh-ed25519, authorized_keys form): clients pin it for SSH to a lab lease. |
last_seen_at optional | timestamp | |
certificate_not_after | timestamp | |
active_leases | integer | |
teardowns_owed | integer | |
devices | integer | |
held_claims | integer | HeldClaims counts the host's devices claimed by a lease (held or awaiting release). |
enrolled_at | timestamp | |
revoked_at optional | timestamp |
LabHostPatch
LabHostPatch changes a lab host; nil fields keep their value.
| Field | Type | Description |
|---|---|---|
name optional | string | |
labels optional | object of string | |
max_leases optional | integer | |
disabled optional | boolean |
LabSelector
LabSelector names the hosts of a lab pool: a host matches when it is listed, when it carries every label (an empty label set matches no host by labels), or when its enrolment token named the pool; and, whichever way it is named, only when it meets the pool's operating system and architecture requirement (OS and Arch; empty allows any).
| Field | Type | Description |
|---|---|---|
host_ids | array of uuid | |
labels | object of string | |
os | array of string | OS lists the operating systems the pool's hosts must run (linux, darwin); empty: any. |
arch | array of string | Arch lists the architectures the pool's hosts must have (Go names: amd64, arm64, ...); empty: any. |
Lease
One holder on one host of a pool.
| Field | Type | Description |
|---|---|---|
id | uuid | |
org_id | uuid | |
pool_id | uuid | |
holder | Holder | |
acting_agent_id optional | uuid | |
state | string | |
size | Size | |
purpose | string | |
repo | string | |
workspace_id optional | uuid | |
lab_host_id optional | uuid | |
approval_id optional | string | |
devices optional | array of LeaseDevice | |
host optional | Host | |
tasks_open optional | boolean | TasksOpen says whether the lease has an agent task that has not ended; set by the single lease read of a cloud or BYOC lease only. |
created_at | timestamp | |
expires_at | timestamp | |
hard_expires_at | timestamp | |
idle_timeout_seconds | integer | |
last_activity_at | timestamp | |
renewals | integer | |
ended_at optional | timestamp | |
end_reason optional | string |
LeaseDevice
A device claimed by a lease.
| Field | Type | Description |
|---|---|---|
device_id | uuid | |
class | string | |
state | string |
LeaseRequest
LeaseRequest asks for a lease of a pool.
| Field | Type | Description |
|---|---|---|
ttl_seconds | integer | |
size | string | |
purpose | string | |
repo | string | |
devices optional | array of DeviceRequest | Claimed on a lab pool's host: each entry names one device by ID or asks for any present, unclaimed device of a class. |
Pool
An organization's set of build capacity.
| Field | Type | Description |
|---|---|---|
id | uuid | |
org_id | uuid | |
name | string | |
description | string | |
backend | string | |
template_id optional | uuid | |
template_version_id optional | uuid | |
lab optional | LabSelector | |
sizes | array of Size | |
default_size | string | |
default_lease_ttl_seconds | integer | |
max_lease_ttl_seconds | integer | |
hard_max_seconds | integer | |
idle_timeout_seconds | integer | |
access | Access | |
requires_approval | boolean | |
egress | Egress | |
cache_volumes | array of CacheVolume | |
record_sessions | boolean | |
max_active_leases | integer | |
log_retention_days | integer | |
artifact_retention_days | integer | How long artifacts of the pool's leases are kept (M3, 14.1). |
disabled | boolean | |
environment_id optional | uuid | |
secrets | array of SecretRef | Delivered to every lease's host. |
task_engines | array of string | The agent task engines the pool's hosts offer; empty offers none. |
task_engine_modes | object of array of string | The permissive modes (taskorder.Engine.Permissive) of each offered engine the pool allows, {engine: [mode]}; an engine absent offers only its non-permissive modes. Allowing one is re-verified (step-up build.task_permissive_mode:enable); never on lab pools. |
task_model_access | object of TaskEngineAccess | Per engine the model access the pool offers; an engine absent from it offers gateway only. Loosening it is re-verified (step-up build.task_model_access:loosen). |
created_by optional | uuid | |
created_at | timestamp | |
updated_at | timestamp | |
version | integer |
PoolEngine
One engine a pool offers, as its hosts report it.
| Field | Type | Description |
|---|---|---|
engine | string | |
display_name | string | How Sandscale names the engine. |
pinned_version | string | The version the registry verified the engine at. |
modes | array of string | The engine's modes; PermissiveModes those of them that are permissive, and AllowedPermissiveModes those the pool allows. |
permissive_modes | array of string | |
allowed_permissive_modes | array of string | |
hosts_reporting | integer | The pool's hosts with a fresh report; HostsInstalled those reporting the engine present, HostsVersionMatch those at the pinned version. |
hosts_installed | integer | |
hosts_version_match | integer | |
last_reported_at optional | timestamp | |
status | string | Status: installed (every reporting host has the pinned version), version_mismatch (every reporting host has it, not all at the pinned version), missing (a reporting host lacks it), unknown (no host reports). |
PoolEngines
The engine report of a pool: its hosts are the hosts of its active leases.
| Field | Type | Description |
|---|---|---|
pool_id | uuid | |
hosts | integer | |
hosts_reporting | integer | |
hosts_with_sudo | integer | HostsWithSudo and HostsWithoutUserSwitch are reporting hosts where a permissive mode is refused (permissive_mode_with_sudo, permissive_mode_same_user). |
hosts_without_user_switch | integer | |
engines | array of PoolEngine |
PoolSpec
The writable part of a pool. A PATCH decodes onto the current pool's spec.
| Field | Type | Description |
|---|---|---|
name | string | |
description | string | |
backend | string | |
template_id optional | uuid | |
template_version_id optional | uuid | |
lab optional | LabSelector | |
sizes | array of Size | |
default_size | string | |
default_lease_ttl_seconds | integer | |
max_lease_ttl_seconds | integer | |
hard_max_seconds | integer | |
idle_timeout_seconds | integer | |
access | Access | |
requires_approval | boolean | |
egress | Egress | |
cache_volumes | array of CacheVolume | |
record_sessions | boolean | |
max_active_leases | integer | |
log_retention_days | integer | |
artifact_retention_days | integer | |
disabled | boolean | |
environment_id optional | uuid | |
secrets | array of SecretRef | |
task_engines | array of string | |
task_model_access | object of TaskEngineAccess | |
task_engine_modes | object of array of string | The permissive engine modes the pool allows, {engine: [mode]}. |
version optional | integer | Version, when set on an update, must be the pool's current version. |
Quotas
The organization's Build Hosts limits.
| Field | Type | Description |
|---|---|---|
max_active_leases | integer | |
max_active_vcpus | integer | |
max_active_leases_per_person | integer | |
max_lease_hours_per_person_month | integer | |
updated_by optional | uuid | |
updated_at optional | timestamp |
Run
A command recorded on a lease before it runs.
| Field | Type | Description |
|---|---|---|
id | uuid | |
lease_id | uuid | |
actor_id | uuid | |
acting_agent_id optional | uuid | The agent that started the run for the holder (M3). |
argv | array of string | |
cwd | string | |
command | string | |
state | string | |
exit_code optional | integer | |
reported_by | string | |
started_at | timestamp | |
finished_at optional | timestamp | |
duration_ms optional | integer | |
log | RunLogInfo |
RunLogInfo
The size and digest of a run's stored log.
| Field | Type | Description |
|---|---|---|
bytes | integer | |
sha256 optional | string |
RunRequest
RunRequest records a command to run on a lease's host.
| Field | Type | Description |
|---|---|---|
argv | array of string | |
cwd | string |
SSHTarget
| Field | Type | Description |
|---|---|---|
user | string | |
workspace_id optional | uuid | |
lab_host_id optional | uuid | |
lease_id optional | uuid | |
host_key_alias | string | |
host_key optional | string | A lab host's SSH host key (authorized_keys form) to pin, as the host last reported it; empty when it reported none yet. |
SecretRef
One Vault value a pool delivers to its leases' hosts: a field of a vault path, as an environment variable (Env) or a file (File). A reference only, never a value.
| Field | Type | Description |
|---|---|---|
path | string | |
field | string | |
env optional | string | |
file optional | string |
Size
One size a pool offers.
| Field | Type | Description |
|---|---|---|
name | string | |
cpu_cores | number | |
memory_gb | number |
SyncPlan
What the client runs: rsync over SSH with the lease's certificate.
| Field | Type | Description |
|---|---|---|
direction | string | |
ssh_user | string | |
remote_dir | string | |
rsync_args | array of string |
SyncRequest
SyncRequest asks for a sync of a source tree with a lease's host.
| Field | Type | Description |
|---|---|---|
direction | string | |
remote_dir | string |
TaskEngineAccess
A pool's model access for one engine.
| Field | Type | Description |
|---|---|---|
modes | array of string | The model access modes the pool offers for the engine (gateway, vendor_account), each at most once, each one the engine supports. |
organization_credential | string | OrganizationCredential names the organization's AI provider key in Vault (its provider the engine's vendor) that vendor_account tasks may use; "" none. |
person_credentials | boolean | PersonCredentials lets each person's vendor_account tasks use the person's own API key. |
TokenRequest
TokenRequest asks for a lab host enrolment token.
| Field | Type | Description |
|---|---|---|
name | string | |
labels | object of string | |
pool_ids | array of uuid | |
ttl_seconds | integer |
Usage
Active and monthly usage, with the limits.
| Field | Type | Description |
|---|---|---|
scope | string | |
month | string | |
active_leases | integer | |
active_vcpus | number | |
lease_hours_month | number | |
active_leases_by_pool optional | object of integer | |
limits | Quotas |
This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.