Sandboxes
58 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.
API reference · Authentication · Errors
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/sandbox/artifacts | List artifacts |
POST | /api/v1/sandbox/artifacts/{id}/approve | Approve an artifact |
POST | /api/v1/sandbox/artifacts/{id}/reject | Reject an artifact |
GET | /api/v1/sandbox/instances | List instances |
POST | /api/v1/sandbox/instances | Create an instance |
GET | /api/v1/sandbox/instances/{id} | Get one instance |
DELETE | /api/v1/sandbox/instances/{id} | Delete one instance |
POST | /api/v1/sandbox/instances/{id}/exec | Exec an instance |
GET | /api/v1/sandbox/instances/{id}/files | Reads a file or lists a directory inside a running sandbox instance, in its own container. |
PUT | /api/v1/sandbox/instances/{id}/files | Writes a file into a running sandbox instance, in its own container. |
GET | /api/v1/sandbox/instances/{id}/logs | As Server-Sent Events. |
GET | /api/v1/sandbox/instances/{id}/metrics | Answers GET .../metrics once the caller may use the sandbox. |
POST | /api/v1/sandbox/instances/{id}/pause | Pause an instance |
GET | /api/v1/sandbox/instances/{id}/ports | The sandbox's open exposures. |
POST | /api/v1/sandbox/instances/{id}/ports | Create a port for an instance |
DELETE | /api/v1/sandbox/instances/{id}/ports/{port} | ({port} is the exposure's ID or its port number). |
GET | /api/v1/sandbox/instances/{id}/ports/{port}/connect | One TCP connection to the exposed port, as a WebSocket of binary messages. |
POST | /api/v1/sandbox/instances/{id}/project | Project an instance |
GET | /api/v1/sandbox/instances/{id}/project/changes | List changes |
GET | /api/v1/sandbox/instances/{id}/pty | Answers GET .../pty once the caller may use the sandbox. |
POST | /api/v1/sandbox/instances/{id}/resume | Resume an instance |
GET | /api/v1/sandbox/instances/{id}/runs | List the runs of an instance |
POST | /api/v1/sandbox/instances/{id}/snapshot | Snapshot an instance |
GET | /api/v1/sandbox/instances/{id}/snapshots | (the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots. |
GET | /api/v1/sandbox/instances/{id}/ssh | The host, user, pinned host key and routes, when the caller may use SSH on the sandbox. |
POST | /api/v1/sandbox/instances/{id}/ssh/certificate | Create a certificate |
GET | /api/v1/sandbox/instances/{id}/ssh/connect | One SSH connection, as a WebSocket of binary messages. |
POST | /api/v1/sandbox/jobs/{id}/input | Handles stdin injection into a running job. POST /api/v1/sandbox/jobs/{id}/input with body {"data":"..."} |
POST | /api/v1/sandbox/jobs/{id}/pty/resize | Handles PTY window resize requests. POST /api/v1/sandbox/jobs/{id}/pty/resize with body {"rows":N,"cols":N} |
GET | /api/v1/sandbox/kill-switch | List kill switch |
GET | /api/v1/sandbox/launch-options | For whoever may start sandboxes (mayStart). Templates are the ready ones the caller may start from (the template list's rule); sizes and refusals follow the policy, the per-member quota and the organization's concurrency limit as the create checks them. |
GET | /api/v1/sandbox/orgs/{id}/billing/usage | List usage |
GET | /api/v1/sandbox/policy | List policy |
PUT | /api/v1/sandbox/policy | Set policy |
GET | /api/v1/sandbox/policy/port-exposure | List port exposure |
PUT | /api/v1/sandbox/policy/port-exposure | The whole policy. Exposures it no longer allows are closed with the change. A change that widens the policy is re-verified: a stolen administrator session cannot open every sandbox's ports. |
GET | /api/v1/sandbox/policy/snapshots | List snapshots |
PUT | /api/v1/sandbox/policy/snapshots | The whole policy. Existing snapshots keep their retention; a lower quota refuses new snapshots until usage is under it. |
GET | /api/v1/sandbox/policy/ssh | List ssh |
PUT | /api/v1/sandbox/policy/ssh | The whole policy. Live sessions it no longer allows end at their next check. |
GET | /api/v1/sandbox/policy/warm-pool | List warm pool |
PUT | /api/v1/sandbox/policy/warm-pool | ]}: the whole set. The maintainer starts and ends members to match within a minute. |
GET | /api/v1/sandbox/quota | List quota |
GET | /api/v1/sandbox/runs | List runs |
GET | /api/v1/sandbox/runs/{id} | Get one run |
DELETE | /api/v1/sandbox/runs/{id} | Cancels a running job by marking it in the store and signaling the assigned worker via a cancellation record. |
GET | /api/v1/sandbox/snapshots | (the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots. |
GET | /api/v1/sandbox/snapshots/{snapshotId} | Get one snapshot |
DELETE | /api/v1/sandbox/snapshots/{snapshotId} | Delete one snapshot |
GET | /api/v1/sandbox/templates | List templates |
POST | /api/v1/sandbox/templates | Records a template from JSON: - name (required): lowercase name matching [a-z0-9][a-z0-9-]*[a-z0-9] - version (optional): semver string, defaults to "0.1.0" - image (required): the OCI image its sandboxes run, pinned by digest - disk_size_mb / mem_size_mb / cpu_count (optional integers) |
GET | /api/v1/sandbox/templates/{id} | Get one template |
DELETE | /api/v1/sandbox/templates/{id} | Delete one template |
GET | /api/v1/sandbox/templates/{id}/build-status | Returns the current build state of a template. With ?watch=true it streams SSE updates every 2 seconds until the build is no longer in "building" state or a 5-minute timeout is reached. |
GET | /api/v1/sandbox/webhooks | List webhooks |
POST | /api/v1/sandbox/webhooks | Create a webhook |
DELETE | /api/v1/sandbox/webhooks/{id} | Delete one webhook |
GET | /api/v1/sandbox/workers | . The route needs ni:sandbox:workers:read (sandbox:admin: account Owners and Admins, and super admins). |
Endpoints
GET /api/v1/sandbox/artifacts
List artifacts
- Permission
sandboxes:read- Query parameters
status- Response
- 200: ListResponse
- Errors
- 503:
service_unavailable
POST /api/v1/sandbox/artifacts/{id}/approve
Approve an artifact
- Permission
sandboxes:write- Path parameters
id- Request body
- object
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 404:not_found; 422:patch_failed; 501:artifact_apply_unavailable; 503:audit_unavailable,service_unavailable
POST /api/v1/sandbox/artifacts/{id}/reject
Reject an artifact
- Permission
sandboxes:write- Path parameters
id- Errors
- 404:
not_found; 503:audit_unavailable,service_unavailable
GET /api/v1/sandbox/instances
List instances
- Permission
sandboxes:use- Query parameters
cursor,limit,project_id,status- Response
- 200: ListResponse
- Errors
- 400:
invalid_cursor,invalid_request; 401:unauthenticated; 403:policy_denied; 404:project_not_found; 409:project_inactive; 503:authorization_unavailable,provisioner_unavailable,service_unavailable
POST /api/v1/sandbox/instances
Create an instance
- Permission
sandboxes:create- Request body
- CreateInstanceRequest
- Response
- 201: CreateInstanceResponse
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 401:unauthenticated; 403:access_denied,policy_denied; 404:project_not_found,snapshot_not_found,template_not_found,workspace_not_found; 409:project_inactive,snapshot_not_ready,snapshot_project_mismatch; 422:environment_setup_failed,snapshot_restore_failed; 429:quota_exceeded; 500:policy_error; 502:snapshot_restore_failed; 503:authorization_unavailable,provisioner_unavailable,service_unavailable,storage_unavailable
GET /api/v1/sandbox/instances/{id}
Get one instance
- Permission
sandboxes:use- Path parameters
id- Response
- 200: InstanceDetail
- Errors
- 404:
workspace_not_found; 503:provisioner_unavailable
DELETE /api/v1/sandbox/instances/{id}
Delete one instance
- Permission
sandboxes:manage- Path parameters
id- Errors
- 404:
workspace_not_found; 503:provisioner_unavailable
POST /api/v1/sandbox/instances/{id}/exec
Exec an instance
- Permission
sandboxes:use- Path parameters
id- Request body
- ExecRequest
- Response
- 200: ExecOutcome
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 403:host_access_denied,policy_denied; 404:workspace_not_found; 409:instance_lost,instance_paused; 500:policy_error; 503:audit_unavailable,authorization_unavailable,dlp_unavailable,service_unavailable
GET /api/v1/sandbox/instances/{id}/files
Reads a file or lists a directory inside a running sandbox instance, in its own container.
- Permission
sandboxes:use- Path parameters
id- Query parameters
path,raw- Response
- 200: PathContent
- Errors
- 400:
invalid_request; 404:not_found,workspace_not_found; 409:instance_lost,instance_paused; 413:file_too_large; 422:exec_failed; 504:agent_timeout
PUT /api/v1/sandbox/instances/{id}/files
Writes a file into a running sandbox instance, in its own container.
- Permission
sandboxes:use- Path parameters
id- Query parameters
mode,path- Request body
- object
- Response
- 200: object of any
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 404:workspace_not_found; 409:instance_lost,instance_paused; 413:file_too_large; 422:exec_failed; 502:transfer_incomplete; 503:provisioner_unavailable,service_unavailable; 504:agent_timeout
GET /api/v1/sandbox/instances/{id}/logs
As Server-Sent Events.
- Permission
sandboxes:use- Path parameters
id- Query parameters
from_chunk,run_id- Errors
- 400:
bad_request; 404:not_found,workspace_not_found; 503:audit_unavailable,dlp_unavailable,service_unavailable
GET /api/v1/sandbox/instances/{id}/metrics
Answers GET .../metrics once the caller may use the sandbox.
- Permission
sandboxes:use- Path parameters
id- Query parameters
start- Response
- 200: SandboxMetrics
- Errors
- 400:
invalid_request; 404:workspace_not_found; 503:provisioner_unavailable
POST /api/v1/sandbox/instances/{id}/pause
Pause an instance
- Permission
sandboxes:manage- Path parameters
id- Errors
- 503:
provisioner_unavailable
GET /api/v1/sandbox/instances/{id}/ports
The sandbox's open exposures.
- Permission
sandboxes:use- Path parameters
id- Response
- 200: object of any
- Errors
- 404:
workspace_not_found
POST /api/v1/sandbox/instances/{id}/ports
Create a port for an instance
- Permission
sandboxes:use- Path parameters
id- Request body
- exposePortRequest
- Response
- PortExposure
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 403:policy_denied,port_exposure_disabled,port_not_allowed; 409:instance_not_running,port_exposed,port_exposure_limit,port_exposure_unsupported; 429:rate_limited; 501:port_exposure_unavailable; 503:audit_unavailable,service_unavailable
DELETE /api/v1/sandbox/instances/{id}/ports/{port}
({port} is the exposure's ID or its port number).
- Permission
sandboxes:use- Path parameters
id,port- Errors
- 403:
policy_denied; 404:not_found; 501:port_exposure_unavailable; 503:audit_unavailable,service_unavailable
GET /api/v1/sandbox/instances/{id}/ports/{port}/connect
One TCP connection to the exposed port, as a WebSocket of binary messages.
- Permission
sandboxes:use- Path parameters
id,port- Errors
- 400:
websocket_required; 403:policy_denied,port_exposure_disabled,port_not_allowed; 404:not_found,workspace_not_found; 409:instance_not_running,port_exposure_unsupported; 410:port_exposure_closed; 422:transfer_failed; 429:rate_limited,tunnel_limit; 501:port_exposure_unavailable; 502:port_refused; 503:audit_unavailable,service_unavailable; 504:tunnel_timeout
POST /api/v1/sandbox/instances/{id}/project
Project an instance
- Permission
sandboxes:use- Path parameters
id- Query parameters
dir- Response
- 200: ProjectUpload
- Errors
- 400:
invalid_project_archive,invalid_request; 403:host_access_denied,policy_denied; 409:instance_paused; 413:project_too_large; 422:project_extract_failed; 429:project_upload_busy; 500:policy_error; 502:transfer_incomplete; 503:audit_unavailable,authorization_unavailable,dlp_unavailable,provisioner_unavailable,service_unavailable
GET /api/v1/sandbox/instances/{id}/project/changes
List changes
- Permission
sandboxes:use- Path parameters
id- Query parameters
dir- Response
- 200: ProjectChanges
- Errors
- 400:
invalid_request; 403:policy_denied; 404:not_found; 422:project_extract_failed; 500:policy_error; 503:audit_unavailable,dlp_unavailable
GET /api/v1/sandbox/instances/{id}/pty
Answers GET .../pty once the caller may use the sandbox.
- Permission
sandboxes:use- Path parameters
id- Errors
- 404:
workspace_not_found; 501:terminal_unavailable
POST /api/v1/sandbox/instances/{id}/resume
Resume an instance
- Permission
sandboxes:manage- Path parameters
id- Errors
- 503:
provisioner_unavailable
GET /api/v1/sandbox/instances/{id}/runs
List the runs of an instance
- Permission
sandboxes:use- Path parameters
id- Response
- 200: ListResponse
- Errors
- 404:
workspace_not_found; 503:service_unavailable
POST /api/v1/sandbox/instances/{id}/snapshot
Snapshot an instance
- Permission
sandboxes:use- Path parameters
id- Request body
- object
- Response
- 201: SnapshotView
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 403:host_access_denied,policy_denied,snapshots_disabled; 409:instance_not_running,instance_paused,snapshot_quota_exceeded; 413:snapshot_too_large; 422:snapshot_failed; 501:snapshots_unavailable; 502:transfer_incomplete; 503:audit_unavailable,authorization_unavailable,service_unavailable,storage_unavailable
GET /api/v1/sandbox/instances/{id}/snapshots
(the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots.
- Permission
sandboxes:use- Path parameters
id- Query parameters
limit- Response
- 200: object of any
- Errors
- 400:
invalid_request; 404:workspace_not_found; 501:snapshots_unavailable; 503:authorization_unavailable
GET /api/v1/sandbox/instances/{id}/ssh
The host, user, pinned host key and routes, when the caller may use SSH on the sandbox.
- Permission
sandboxes:use- Path parameters
id- Response
- 200: SSHInfo
- Errors
- 403:
host_access_denied,policy_denied,ssh_disabled; 409:instance_not_running,instance_paused,ssh_unsupported; 501:ssh_unavailable; 503:authorization_unavailable
POST /api/v1/sandbox/instances/{id}/ssh/certificate
Create a certificate
- Permission
sandboxes:use- Path parameters
id- Request body
- object
- Response
- 200: SSHCertificateResponse
- Errors
- 400:
invalid_body,invalid_json,invalid_request,ssh_key_refused; 403:policy_denied,ssh_disabled; 409:instance_not_running,ssh_unsupported; 503:ssh_ca_unavailable
GET /api/v1/sandbox/instances/{id}/ssh/connect
One SSH connection, as a WebSocket of binary messages.
- Permission
sandboxes:use- Path parameters
id- Errors
- 400:
websocket_required; 403:host_access_denied,policy_denied,ssh_disabled; 404:workspace_not_found; 409:instance_not_running,instance_paused,ssh_unsupported; 422:transfer_failed; 501:ssh_unavailable; 503:authorization_unavailable,ssh_ca_unavailable; 504:tunnel_timeout
POST /api/v1/sandbox/jobs/{id}/input
Handles stdin injection into a running job. POST /api/v1/sandbox/jobs/{id}/input with body {"data":"..."}
- Permission
sandboxes:use- Path parameters
id- Request body
- object
- Errors
- 400:
bad_request; 401:unauthenticated; 403:access_denied; 404:not_found; 410:session_closed; 501:pty_unavailable; 503:authorization_unavailable,service_unavailable
POST /api/v1/sandbox/jobs/{id}/pty/resize
Handles PTY window resize requests. POST /api/v1/sandbox/jobs/{id}/pty/resize with body {"rows":N,"cols":N}
- Permission
sandboxes:use- Path parameters
id- Request body
- object
- Errors
- 400:
bad_request; 401:unauthenticated; 403:access_denied; 404:not_found; 410:session_closed; 501:pty_unavailable; 503:authorization_unavailable,service_unavailable
GET /api/v1/sandbox/kill-switch
List kill switch
- Permission
sandboxes:read- Response
- 200: KillSwitchState
GET /api/v1/sandbox/launch-options
For whoever may start sandboxes (mayStart). Templates are the ready ones the caller may start from (the template list's rule); sizes and refusals follow the policy, the per-member quota and the organization's concurrency limit as the create checks them.
- Permission
sandboxes:create- Response
- 200: LaunchOptions
- Errors
- 401:
unauthenticated; 503:authorization_unavailable,service_unavailable
GET /api/v1/sandbox/orgs/{id}/billing/usage
List usage
- Permission
billing:read- Path parameters
id- Query parameters
end,start- Response
- 200: WorkspaceBillingUsageResponse
- Errors
- 400:
invalid_request; 401:unauthenticated; 403:iam_denied; 503:service_unavailable
GET /api/v1/sandbox/policy
List policy
- Permission
sandboxes:read- Response
- 200: PolicyResponse
- Errors
- 503:
service_unavailable
PUT /api/v1/sandbox/policy
Set policy
- Permission
sandboxes:write- Request body
- PolicyUpdateRequest
- Response
- 200: PolicyResponse
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 503:audit_unavailable,service_unavailable
GET /api/v1/sandbox/policy/port-exposure
List port exposure
- Permission
sandboxes:read- Response
- 200: PortPolicy
- Errors
- 503:
service_unavailable
PUT /api/v1/sandbox/policy/port-exposure
The whole policy. Exposures it no longer allows are closed with the change. A change that widens the policy is re-verified: a stolen administrator session cannot open every sandbox's ports.
- Permission
sandboxes:write- Request body
- PortPolicy
- Response
- 200: PortPolicy
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 503:audit_unavailable,service_unavailable,step_up_unavailable
GET /api/v1/sandbox/policy/snapshots
List snapshots
- Permission
sandboxes:read- Response
- 200: SnapshotPolicy
- Errors
- 503:
service_unavailable
PUT /api/v1/sandbox/policy/snapshots
The whole policy. Existing snapshots keep their retention; a lower quota refuses new snapshots until usage is under it.
- Permission
sandboxes:write- Request body
- SnapshotPolicy
- Response
- 200: SnapshotPolicy
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 503:audit_unavailable,service_unavailable
GET /api/v1/sandbox/policy/ssh
List ssh
- Permission
sandboxes:read- Response
- 200: SSHPolicy
- Errors
- 503:
service_unavailable
PUT /api/v1/sandbox/policy/ssh
The whole policy. Live sessions it no longer allows end at their next check.
GET /api/v1/sandbox/policy/warm-pool
List warm pool
- Permission
sandboxes:read- Response
- 200: WarmPoolPolicy
- Errors
- 501:
warm_pool_unavailable
PUT /api/v1/sandbox/policy/warm-pool
]}: the whole set. The maintainer starts and ends members to match within a minute.
- Permission
sandboxes:write- Request body
- object
- Response
- 200: WarmPoolPolicy
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 501:warm_pool_unavailable; 503:audit_unavailable
GET /api/v1/sandbox/quota
List quota
- Permission
sandboxes:create- Response
- 200: QuotaResponse
- Errors
- 401:
unauthenticated; 503:provisioner_unavailable
GET /api/v1/sandbox/runs
List runs
- Permission
sandboxes:use- Query parameters
from,limit,offset,project_id,status,to,user_id- Response
- 200: ListResponse
- Errors
- 400:
invalid_request; 401:unauthenticated; 503:authorization_unavailable,service_unavailable
GET /api/v1/sandbox/runs/{id}
Get one run
- Permission
sandboxes:use- Path parameters
id- Response
- 200: RunDetail
- Errors
- 401:
unauthenticated; 403:access_denied; 404:not_found; 503:authorization_unavailable,service_unavailable
DELETE /api/v1/sandbox/runs/{id}
Cancels a running job by marking it in the store and signaling the assigned worker via a cancellation record.
- Permission
sandboxes:use- Path parameters
id- Errors
- 401:
unauthenticated; 403:access_denied; 404:not_found; 409:already_finished; 503:audit_unavailable,authorization_unavailable,service_unavailable
GET /api/v1/sandbox/snapshots
(the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots.
- Permission
sandboxes:use- Query parameters
limit- Response
- 200: object of any
- Errors
- 400:
invalid_request; 404:workspace_not_found; 501:snapshots_unavailable; 503:authorization_unavailable
GET /api/v1/sandbox/snapshots/{snapshotId}
Get one snapshot
- Permission
sandboxes:use- Path parameters
snapshotId- Response
- 200: SnapshotView
- Errors
- 404:
snapshot_not_found; 501:snapshots_unavailable; 503:authorization_unavailable
DELETE /api/v1/sandbox/snapshots/{snapshotId}
Delete one snapshot
- Permission
sandboxes:use- Path parameters
snapshotId- Errors
- 404:
snapshot_not_found; 503:audit_unavailable,authorization_unavailable
GET /api/v1/sandbox/templates
List templates
- Permission
sandboxes:use- Response
- 200: ListResponse
- Errors
- 401:
unauthenticated; 503:authorization_unavailable,service_unavailable
POST /api/v1/sandbox/templates
Records a template from JSON: - name (required): lowercase name matching [a-z0-9][a-z0-9-]*[a-z0-9] - version (optional): semver string, defaults to "0.1.0" - image (required): the OCI image its sandboxes run, pinned by digest - disk_size_mb / mem_size_mb / cpu_count (optional integers)
- Permission
sandboxes:write- Request body
- object
- Response
- 201: TemplateDetail
- Errors
- 400:
invalid_body,invalid_json,invalid_request; 501:template_build_unavailable; 503:audit_unavailable,service_unavailable
GET /api/v1/sandbox/templates/{id}
Get one template
- Permission
sandboxes:read- Path parameters
id- Response
- 200: TemplateDetail
- Errors
- 404:
template_not_found; 503:service_unavailable
DELETE /api/v1/sandbox/templates/{id}
Delete one template
- Permission
sandboxes:manage- Path parameters
id- Errors
- 404:
template_not_found; 409:template_in_use; 503:audit_unavailable,service_unavailable
GET /api/v1/sandbox/templates/{id}/build-status
Returns the current build state of a template. With ?watch=true it streams SSE updates every 2 seconds until the build is no longer in "building" state or a 5-minute timeout is reached.
- Permission
sandboxes:read- Path parameters
id- Query parameters
watch- Response
- 200: object of any
- Errors
- 404:
template_not_found; 503:service_unavailable
GET /api/v1/sandbox/webhooks
List webhooks
- Permission
webhooks:read- Errors
- 501:
not_implemented
POST /api/v1/sandbox/webhooks
Create a webhook
- Permission
webhooks:create- Errors
- 501:
not_implemented
DELETE /api/v1/sandbox/webhooks/{id}
Delete one webhook
- Permission
webhooks:delete- Path parameters
id- Errors
- 501:
not_implemented
GET /api/v1/sandbox/workers
. The route needs ni:sandbox:workers:read (sandbox:admin: account Owners and Admins, and super admins).
- Permission
sandboxes:read- Response
- 200: WorkersResponse
- Errors
- 401:
unauthenticated; 503:service_unavailable
Objects
object
| Field | Type | Description |
|---|---|---|
target_path | string |
object
| Field | Type | Description |
|---|---|---|
label | string |
object
| Field | Type | Description |
|---|---|---|
public_key | string |
object
| Field | Type | Description |
|---|---|---|
data | string | Base64-encoded bytes |
object
| Field | Type | Description |
|---|---|---|
rows | integer | |
cols | integer |
object
| Field | Type | Description |
|---|---|---|
name | string | |
version | string | |
image | string | |
disk_size_mb | integer | |
mem_size_mb | integer | |
cpu_count | integer |
object
| Field | Type | Description |
|---|---|---|
path | string | |
content | string | Base64-encoded |
mode | string |
object
| Field | Type | Description |
|---|---|---|
pools | array of WarmPoolEntry |
Cost
What a resource's running time cost: in total and in the current month (UTC).
| Field | Type | Description |
|---|---|---|
total | Money | |
this_month | Money |
Money
An amount in US dollars: USD exactly (six decimals, for clients that compute), and Display as people see it. Display has two decimals ("$1,234.56"), "under $0.01" for an amount above zero that rounds below a cent, or the reason there is no amount.
| Field | Type | Description |
|---|---|---|
usd | string | |
display | string |
Runtime
The runtime a sandbox or workspace ran on.
| Field | Type | Description |
|---|---|---|
kind | string | Firecracker, docker_gvisor, docker, kubernetes, gvisor (a gVisor container whose runtime was not recorded) or not_recorded. |
label | string | The kind in words: "Firecracker microVM", "Docker (gVisor)", "Docker", "Kubernetes", "gVisor container" or "Not recorded". |
ArtifactDetail
The artifact representation.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed. |
run_id | string | |
file_path | string | |
additions | integer | |
deletions | integer | |
size_bytes | integer | |
status | string | |
approved_by optional | string | |
approved_at optional | timestamp | |
target_path optional | string |
CreateInstanceRequest
| Field | Type | Description |
|---|---|---|
template_id optional | string | |
command optional | array of string | |
env optional | object of string | |
mem_mb optional | integer | |
cpu_count optional | integer | |
disk_mb optional | integer | The size of the sandbox's /workspace (0: the template's, else the worker's default); bounded by the policy's max_disk_mb and placed only on a worker that can hold it. |
image optional | string | The OCI image the sandbox runs, pinned by digest (name@sha256:...); empty: the template's image, else the worker's default. The sandbox is placed only on a worker that runs images of its own (custom_images) and starts only if the image's repository is on that worker's allowlist. |
ttl_seconds optional | integer | |
secret_refs optional | array of string | |
metadata optional | object of string | |
name optional | string | An optional display name (1 to 64 characters, no control characters). |
labels optional | object of string | Optional key/value labels. |
network optional | string | The network mode: empty or "none" (no network). A mode the policy lists but the runtime does not enforce is refused (GET /api/v1/sandbox/launch-options says which). |
environment_id optional | string | EnvironmentID places the sandbox in a cloud environment GET /api/v1/sandbox/launch-options lists; empty uses the product's default environment, or none. On a cell without cloud environments any value is refused rather than ignored. |
product optional | string | The product the sandbox is a session of: agents, cli or sandboxes (default). |
snapshot_id optional | string | SnapshotID starts the sandbox from a snapshot: its workspace is restored, it runs in the snapshot's project and, unless the request names one, with its template or image. |
CreateInstanceResponse
| Field | Type | Description |
|---|---|---|
id | string | |
status | string | |
worker_node optional | string | |
created_at | timestamp |
ExecOutcome
A finished command.
| Field | Type | Description |
|---|---|---|
run_id | string | |
exit_code | integer | |
stdout | string | |
stderr | string | |
duration_ms | integer | |
oom_killed | boolean | |
timed_out | boolean |
ExecRequest
| Field | Type | Description |
|---|---|---|
command | array of string | |
env optional | object of string | |
workdir optional | string | |
timeout_sec optional | integer | |
stdin optional | string | Optional base64-encoded bytes piped to the process standard input. |
InstanceDetail
The full instance representation.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed. |
org_id | string | |
user_id | string | |
template_id optional | string | |
worker_id optional | string | |
status | string | |
provider | string | The worker pool's registered provider. It is not the runtime the sandbox ran on (Firecracker workers register as "docker"): that is Runtime. |
runtime | Runtime | The runtime the sandbox ran on, decided by Sandscale from what it recorded when the sandbox was placed ("Not recorded" for sandboxes started before it did). |
started_at optional | timestamp | |
terminated_at optional | timestamp | |
runtime_stopped_at optional | timestamp | When the sandbox's container or microVM was confirmed removed (on the detail of one sandbox): an ended sandbox without it may still hold its worker's resources until the stop sweep or the worker's restart removes them. |
ttl_seconds | integer | |
mem_mb | integer | |
cpu_count | integer | |
cost_usd | string | Cost.Total in dollars (six decimals); "" when not metered. |
cost | Cost | What the sandbox's running time cost at list price, from the billing usage ledger, in total and this month, with the display Sandscale formats. |
metadata optional | object of string | |
name optional | string | |
labels optional | object of string | |
network optional | string | |
environment_id optional | string | The cloud environment the sandbox started in, which decided its network access; empty for none. |
started_by optional | StartedBy | StartedBy says who started the sandbox, described by Sandscale (nil without the store). |
files optional | InstanceFiles | Files says whether the sandbox's workspace can be read and written (GET and PUT .../files): while it runs, in the one container all its commands run in. |
status_reason optional | string | StatusReason says why the sandbox failed or ended (its worker stopped responding, its container is gone, its time to live ended). |
isolation optional | InstanceIsolation | How the sandbox is isolated: a Firecracker microVM or a gVisor container (absent for sandboxes started before Sandscale recorded it). |
suspend optional | InstanceSuspend | Suspend says whether the sandbox can be paused or resumed now (absent once it ended). |
InstanceFiles
InstanceFiles says whether a sandbox's workspace files can be read, and why not.
| Field | Type | Description |
|---|---|---|
available | boolean | |
reason optional | string |
InstanceIsolation
How a sandbox is isolated.
| Field | Type | Description |
|---|---|---|
kind | string | Microvm_firecracker, container_gvisor or container. |
label | string | The kind in words: "microVM (Firecracker)", "container (gVisor)" or "container". |
InstanceSuspend
InstanceSuspend says what pause and resume can do for a sandbox now.
| Field | Type | Description |
|---|---|---|
can_pause | boolean | |
can_resume | boolean | |
reason optional | string |
KillSwitchState
| Field | Type | Description |
|---|---|---|
engaged | boolean | The organization kill switch (agent_kill_switch_state). |
generation | integer | Generation counts its changes (the signed agent policy carries the same number). |
engaged_at optional | timestamp | |
sources | array of string | What engaged it (ai_soc, endpoint). |
platform_engaged | boolean | The cell's switch, which the operator sets. |
platform_reason optional | string |
LaunchChoice
One value of a choice with its label.
| Field | Type | Description |
|---|---|---|
value | string | |
label | string | |
description optional | string | |
available | boolean | |
reason optional | string |
LaunchEnvironments
The environments a sandbox may be placed in. Default is the environment a create without environment_id starts in (the account's default for sandboxes), empty for none; DefaultRefusal says why that default cannot be used by the caller, so a create without environment_id would be refused. An environment decides the sandbox's network access, setup script and variables.
| Field | Type | Description |
|---|---|---|
required | boolean | |
default optional | string | |
default_refusal optional | string | |
options | array of LaunchChoice |
LaunchFeature
Whether a sandbox feature is offered here, and why not.
| Field | Type | Description |
|---|---|---|
available | boolean | |
code optional | string | |
reason optional | string |
LaunchLabelRules
The label rules.
| Field | Type | Description |
|---|---|---|
max_count | integer | |
key_pattern | string | |
max_value_length | integer |
LaunchNameRule
The name rule.
| Field | Type | Description |
|---|---|---|
max_length | integer |
LaunchNetwork
The network modes, the default first.
| Field | Type | Description |
|---|---|---|
default | string | |
options | array of LaunchChoice |
LaunchOptions
| Field | Type | Description |
|---|---|---|
can_start | boolean | |
refusal optional | LaunchRefusal | |
templates | array of LaunchTemplate | |
size | LaunchSize | |
ttl | LaunchTTLOptions | |
network | LaunchNetwork | |
name | LaunchNameRule | |
labels | LaunchLabelRules | |
environments | LaunchEnvironments | The cloud environments the caller may start the sandbox in; empty when none are offered, and a client shows a picker only when Sandscale lists options. |
features | object of LaunchFeature | The sandbox features this deployment offers, decided by the server from what it runs: a client offers a feature only when it is available and shows the reason when it is not. |
LaunchRefusal
LaunchRefusal says why no sandbox can be started now.
| Field | Type | Description |
|---|---|---|
code | string | |
message | string |
LaunchSize
The size of a sandbox started without a template (a template's own size is fixed): the CPU and memory choices within the policy and the caller's quota, and the defaults. Note says where the bounds come from.
| Field | Type | Description |
|---|---|---|
cpu_choices | array of integer | |
mem_mb_choices | array of integer | |
default_cpu | integer | |
default_mem_mb | integer | |
max_cpu | integer | |
max_mem_mb | integer | |
note | string |
LaunchTTLChoice
One time to live, in seconds.
| Field | Type | Description |
|---|---|---|
seconds | integer | |
label | string |
LaunchTTLOptions
The times to live a sandbox may be started with.
| Field | Type | Description |
|---|---|---|
choices | array of LaunchTTLChoice | |
default_seconds | integer | |
max_seconds | integer |
LaunchTemplate
A ready template the caller may start from. Startable is false with Reason when its size is over what the caller may start now.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | |
name | string | |
version | string | |
cpu_count | integer | |
mem_mb | integer | |
startable | boolean | |
reason optional | string | |
builtin optional | boolean | Builtin marks a built-in template: always offered, not a row of the organization, started with its image at the size the request gives. |
image optional | string | A built-in template's image ("" for the workers' default). |
description optional | string | Description says what a built-in template runs. |
warm_idle optional | integer | How many sandboxes of this template wait started in the organization's warm pool (a start of the default size claims one). |
ListResponse
The paginated response wrapper.
| Field | Type | Description |
|---|---|---|
data | array of ArtifactDetail | |
next_cursor optional | string | |
has_more | boolean |
PathContent
A file's content or a directory's entries.
| Field | Type | Description |
|---|---|---|
type | string | |
path | string | |
content optional | string | |
size_bytes optional | integer | |
entries optional | array of PathEntry | A directory's entries (empty, never absent, for an empty directory). |
PathEntry
One entry of a directory.
| Field | Type | Description |
|---|---|---|
name | string | |
type | string | |
size_bytes | integer |
PolicyResponse
The sandbox policy for an org.
| Field | Type | Description |
|---|---|---|
max_concurrent | integer | |
max_exec_time_sec | integer | |
max_mem_mb | integer | |
max_cpu | integer | |
max_disk_mb optional | integer | |
max_workspaces_per_user optional | integer | |
max_cpu_cores_per_user optional | integer | |
max_memory_gb_per_user optional | integer | |
egress_allowlist | array of string | |
allowed_providers | array of string |
PolicyUpdateRequest
| Field | Type | Description |
|---|---|---|
max_concurrent optional | integer | |
max_exec_time_sec optional | integer | |
max_mem_mb optional | integer | |
max_cpu optional | integer | |
max_disk_mb optional | integer | MaxDiskMB caps a sandbox's disk_mb; 0 removes the cap (the workers' maximum still applies). |
max_workspaces_per_user optional | integer | |
max_cpu_cores_per_user optional | integer | |
max_memory_gb_per_user optional | integer | |
egress_allowlist optional | array of string | |
allowed_providers optional | array of string |
PortExposure
An exposure as the API shows it.
| Field | Type | Description |
|---|---|---|
id | string | |
instance_id | string | |
port | integer | |
protocol | string | |
status | string | |
created_by | string | |
created_at | timestamp | |
expires_at | timestamp | |
closed_at optional | timestamp | |
close_reason optional | string | |
connect_path | string | The WebSocket route of a connection, on the API origin, with the caller's own credentials; only the exposure's creator may connect. |
subprotocol | string | The WebSocket subprotocol ConnectPath speaks. |
PortPolicy
The organization's port exposure policy (GET/PUT /api/v1/sandbox/policy/port-exposure).
| Field | Type | Description |
|---|---|---|
mode | string | Off, owner (the person who started the sandbox) or users (anyone who may use it). |
allowed_ports | array of string | The ports that may be exposed: single ports ("8080") or ranges ("3000-3999"), at most 32. |
default_ttl_seconds | integer | An exposure's time to live when the request names none; MaxTTLSeconds the longest it may ask for (60 to 86400). |
max_ttl_seconds | integer | |
max_open_per_sandbox | integer | MaxOpenPerSandbox bounds one sandbox's open exposures (1 to 64). |
ProjectChanges
| Field | Type | Description |
|---|---|---|
dir | string | |
changed | array of string | |
truncated | boolean | |
run_id | string |
ProjectSkip
A file the upload left out, and why: gitignored, special_file, or denied:<rule>.
| Field | Type | Description |
|---|---|---|
path | string | |
reason | string |
ProjectUpload
The outcome of an upload.
| Field | Type | Description |
|---|---|---|
dir | string | |
files | integer | |
bytes | integer | |
skipped | object of integer | Skipped counts the files left out by reason class (gitignored, denied, special_file). |
skipped_paths | array of ProjectSkip | SkippedPaths names up to 100 of them. |
run_id | string | The run of the unpack command. |
QuotaResponse
The current quota state for an org.
| Field | Type | Description |
|---|---|---|
active_instances | integer | |
max_instances | integer | |
cpu_used | integer | |
cpu_max | integer | |
mem_used_mb | integer | |
mem_max_mb | integer | |
cost_this_month_usd | string |
RunDetail
The full run representation.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed. |
org_id optional | string | |
instance_id | string | |
project_id optional | string | |
user_id optional | string | |
tool_identity optional | string | |
policy_version optional | string | |
policy_decision optional | string | |
worker_id optional | string | |
provider optional | string | |
image optional | string | |
status optional | string | |
command | array of string | |
created_at optional | timestamp | |
dispatched_at optional | timestamp | |
exit_code optional | integer | |
started_at | timestamp | |
finished_at optional | timestamp | |
ended_at optional | timestamp | |
duration_ms optional | integer | |
ram_mb_used optional | integer | |
cpu_seconds optional | string | |
memory_gb_seconds optional | string | |
cost_usd | string | |
cost | Money | CostUSD with the display Sandscale formats. |
artifact_ids optional | array of string |
SSHCertificateResponse
SSHCertificateResponse answers POST .../ssh/certificate.
| Field | Type | Description |
|---|---|---|
host | string | |
user | string | |
known_hosts | string | The sandbox's pinned host key as a known_hosts line for Host. |
host_key_sha256 | string | |
certificate_path | string | |
connect_path | string | |
subprotocol | string | |
cert_ttl_seconds | integer | |
certificate | string | |
serial | string | |
key_id | string | |
valid_before | timestamp |
SSHInfo
| Field | Type | Description |
|---|---|---|
host | string | |
user | string | |
known_hosts | string | The sandbox's pinned host key as a known_hosts line for Host. |
host_key_sha256 | string | |
certificate_path | string | |
connect_path | string | |
subprotocol | string | |
cert_ttl_seconds | integer |
SSHPolicy
The organization's SSH policy (GET/PUT /api/v1/sandbox/policy/ssh).
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
mode | string | Owner (the person who started the sandbox) or users (anyone who may use it). |
cert_ttl_seconds | integer | A certificate's life (60 to 3600; the authority caps it at 10 minutes). |
max_session_seconds | integer | MaxSessionSeconds bounds one session (300 to 86400). |
SandboxAllocation
A sandbox's allocated resources.
| Field | Type | Description |
|---|---|---|
cpu_count | integer | |
mem_total_mb | integer |
SandboxMetrics
| Field | Type | Description |
|---|---|---|
instance_id | string | |
status | string | |
allocation | SandboxAllocation | What the sandbox was given (the limits of every sample). |
metrics | array of object of any | The samples since start, oldest first: {timestamp, cpu_used_pct, cpu_count, mem_used_mb, mem_total_mb, disk_used_mb, disk_total_mb}. Empty while Available is false. |
available | boolean | False when this deployment does not sample usage, with Code and Reason. |
code optional | string | |
reason optional | string |
SharedWorkersView
The shared fleet of the cell as an aggregate: counts, sandbox slots, the runtimes offered and the region. It never names a node, an address or another organization.
| Field | Type | Description |
|---|---|---|
healthy | integer | |
unresponsive | integer | |
capacity | integer | |
in_use | integer | |
providers | array of string | |
runtimes | array of Runtime | The runtimes the healthy shared workers offer, from their capabilities. |
region | string |
SnapshotPolicy
The organization's snapshot policy (GET/PUT /api/v1/sandbox/policy/snapshots).
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
max_snapshots | integer | MaxSnapshots bounds the organization's live snapshots (1 to 10000). |
max_total_bytes | integer | MaxTotalBytes bounds their stored bytes; MaxSnapshotBytes one snapshot's (it is also bounded by the deployment's file transfer limit). |
max_snapshot_bytes | integer | |
retention_days | integer | How long a snapshot is kept (1 to 3650). |
SnapshotView
A snapshot as the API shows it.
| Field | Type | Description |
|---|---|---|
id | string | |
instance_id | string | |
project_id optional | string | |
classification | string | |
template_id optional | string | |
image optional | string | |
label | string | |
status | string | |
size_bytes | integer | |
sha256 optional | string | |
created_by | string | |
created_at | timestamp | |
ready_at optional | timestamp | |
expires_at | timestamp | |
failure optional | string |
StartedBy
Who started a sandbox as Sandscale describes it to the caller: Kind is "person" (a signed-in person, from the console or the API), "api_key" (an API key, the SDK), "agent" (an agent through the sandbox MCP server) or "unknown" (started before Sandscale recorded it). Label names the starter ("You" for the caller) and Detail says how the sandbox was started, so a client renders both as they are.
| Field | Type | Description |
|---|---|---|
kind | string | |
label | string | |
detail | string | |
user_id optional | string | |
api_key_id optional | string | |
is_caller | boolean |
StripeMeterEvent
A neutral event shape that can be mapped to Stripe meters.
| Field | Type | Description |
|---|---|---|
event_name | string | |
timestamp | integer | |
identifier | string | |
payload | StripeMeterPayload |
StripeMeterPayload
StripeMeterPayload contains the billable quantity and workspace dimensions.
| Field | Type | Description |
|---|---|---|
value | integer | |
workspace_id | string | |
template_id optional | string | |
org_id | string | |
cpu_cores | integer | |
memory_gb | number | |
storage_gb optional | number |
TemplateDetail
The template representation.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed. |
org_id | string | |
name | string | |
version | string | |
status | string | |
disk_size_mb | integer | |
mem_size_mb | integer | |
cpu_count | integer | |
image optional | string | The image the template's sandboxes run, pinned by digest ("": the worker's default image). |
created_by | string | |
created_at | timestamp |
WarmPoolEntry
One pool: its template ("builtin:<name>" or a template ID), its size, and the members waiting now.
| Field | Type | Description |
|---|---|---|
template | string | |
size | integer | |
idle | integer |
WarmPoolPolicy
| Field | Type | Description |
|---|---|---|
pools | array of WarmPoolEntry | |
max_per_template | integer | The deployment's bounds (read-only). |
max_per_org | integer | |
idle_ttl_seconds | integer |
WorkerView
One sandbox worker in GET /api/v1/sandbox/workers. Pool is "shared" (a worker of the cell that serves every organization without workers of its own) or "byoc" (a worker in an organization's own cloud account). OrgID is set only in the platform scope.
| Field | Type | Description |
|---|---|---|
id | string | |
node_name | string | |
provider | string | |
status | string | |
health | string | |
active_count | integer | |
capacity | integer | |
last_heartbeat | timestamp | |
version | string | |
runtime | Runtime | The runtime the worker runs sandboxes on, from its reported capabilities (Provider is the pool's registered provider, "docker" for Firecracker workers too). |
pool | string | |
org_id optional | string | |
byoc_worker_id optional | string |
WorkersResponse
| Field | Type | Description |
|---|---|---|
scope | string | |
placement optional | string | |
placeable | integer | |
data | array of WorkerView | |
shared | SharedWorkersView | |
has_more | boolean | |
checked_at | timestamp |
WorkspaceBillingUsageAggregate
WorkspaceBillingUsageAggregate reports query-time aggregate metering totals.
| Field | Type | Description |
|---|---|---|
period | string | |
workspace_minutes | integer | |
cpu_core_minutes | integer | |
memory_gb_minutes | number | |
storage_gb_minutes optional | number |
WorkspaceBillingUsageResponse
WorkspaceBillingUsageResponse reports workspace-minute metering data for an org.
| Field | Type | Description |
|---|---|---|
org_id | string | |
start | timestamp | |
end | timestamp | |
daily | array of WorkspaceBillingUsageAggregate | |
monthly | array of WorkspaceBillingUsageAggregate | |
stripe_meter_events | array of StripeMeterEvent |
exposePortRequest
| Field | Type | Description |
|---|---|---|
port | integer | |
protocol optional | string | |
ttl_seconds optional | integer |
This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.