HTTP API

Authentication

Send requests to:

https://api.sandbox.lithosai.cloud

Use an API key from Console → API Keys in the Authorization header. Requests operate within the key’s organization. The following example expects the key in LITHOSBOX_TOKEN and lists that organization’s sandboxes:

curl -fsS https://api.sandbox.lithosai.cloud/vms \
  -H "Authorization: Bearer $LITHOSBOX_TOKEN"

Send JSON request bodies with Content-Type: application/json. Fields ending in _unix_ns use Unix nanoseconds; fields ending in _unix use Unix seconds. Time-range query parameters use RFC3339 timestamps.

Sandboxes

Create a sandbox

POST /vms returns 201 and a sandbox object. Send {} to use the default environment, or choose at most one source:

Field	Purpose
`image`	OCI image reference.
`template`	Template ID, name, or `name:version`.
`snapshot_id`	Snapshot to restore into a new sandbox.

Optional fields are cpus, memory_mb, runtime, disable_internet, allow_egress, writable_size_bytes, dataset or datasets, timeout_s, and vm_id. See Limits for valid values. Template and snapshot restores retain their source configuration. dataset names a read-only dataset granted to your organization and mounts it at /datasets/<name>. To attach several, send "datasets": ["a", "b"] instead: up to 10 distinct names, each mounted at /datasets/<name> in the order given. Send one of dataset or datasets, not both. Send them with image or with neither source; combining them with template or snapshot_id returns 400. Datasets are fixed at creation. See Datasets.

{
  "image": "python:3.12-slim",
  "cpus": 2,
  "memory_mb": 2048
}

allow_egress is a list of destinations the sandbox may still reach, with all other outbound traffic blocked: hostnames, *. wildcards, and public IPv4 addresses or CIDRs, up to 256. A non-empty list implies disable_internet. A create from a snapshot without allow_egress keeps the snapshot’s list. See Outbound network policy. timeout_s is the sandbox’s lifetime in whole seconds: the sandbox is deleted that long after its creation, whatever its state, just as DELETE /vms/{id} would. Omit it for the platform default (no lifetime); 0 asks for none. Values from 0 to 3153600000 (100 years) are accepted; anything else, including a fraction or a string, returns 400. The lifetime is fixed at creation. See Set a lifetime. Provide a UUID in vm_id and reuse it when retrying the same create request. If you lose the response, check GET /vms/{id} before issuing a new create. The Python SDK supplies and reuses an ID automatically within each create call.

Find or delete sandboxes

Route	Response
`GET /vms`	`{"vms": [...]}`
`GET /vms/{id}`	Sandbox object
`DELETE /vms/{id}`	`204`; repeating deletion is safe

The sandbox object includes these fields:

Field	Meaning
`vm_id`	Sandbox ID.
`tenant`	Organization ID.
`state`	Current sandbox state.
`image`, `runtime`	Starting image and runtime.
`cpus`, `memory_mb`	CPU and memory configuration.
`disable_internet`	Whether outbound internet access is disabled. `true` whenever `allow_egress` is set.
`allow_egress`	Allowed outbound destinations, in lowercase without duplicates. `[]` when the sandbox has none.
`created_unix_ns`	Creation time in Unix nanoseconds.
`timeout_s`	Lifetime in seconds; `0` when the sandbox has none.
`expires_unix_ns`	When the lifetime ends, in Unix nanoseconds (`created_unix_ns` plus `timeout_s`); `0` when the sandbox has none.
`parent_vm_id`	Original sandbox ID when created by a fork.
`datasets`	Names of the attached datasets, in order. Present only when the sandbox has any.
`dataset`	Name of the first attached dataset. Present only when the sandbox has any.
`archive_data_bytes`	Size of an archived sandbox’s data, in real bytes. `0` when it is not archived or not yet measured.

Common states are creating, running, slept, archived, interrupted, deleting, and failed. Transitions may also report waking, archiving, or migrating. Use the state and error response to decide which action is available; see Lifecycle actions.

Run a command

POST /vms/{id}/exec accepts an argument list:

{
  "args": ["python3", "-c", "print(42)"]
}

Use stdin_b64 for base64-encoded input, with at most 4 MiB of decoded data. For shell syntax, pass args such as ["sh", "-c", "pwd && ls"]. The response includes exit_code, stdout, stderr, stdout_truncated, and stderr_truncated. Check the exit code; a successful HTTP response does not mean the command succeeded. Foreground completion does not imply every child process has exited. See Run commands for background-job patterns.

Keep a shell session

Use the same session_id for commands that need shared working-directory and environment state:

{
  "session_id": "my-shell",
  "command": "mkdir -p /work && cd /work"
}

Send another command with that ID to continue in the same shell. Close it by sending {"session_id": "my-shell", "close_session": true} to the same endpoint. Sessions have the same synchronous command deadline as ordinary execution.

Lifecycle actions

Route	Response and behavior
`POST /vms/{id}/sleep`	`{"slept": true}` or `{"slept": false}`. A busy sandbox stays awake rather than having its work frozen. ANY later command or file access wakes a sleeping sandbox transparently — there is no wake route to call.
`POST /vms/{id}/stop`	`{"stopped": true}`. Archive the sandbox for later. An archive still running after about 110 seconds returns `202` with `{"stopped": false, "state": "archiving"}` and continues; poll `GET /vms/{id}` until `state` is `archived`.
`POST /vms/{id}/start`	`{"started": true, ...}`. Unarchive and continue.
`POST /vms/{id}/reboot`	Updated sandbox object. Keep files and restart the environment; processes and sessions end.

The HTTP routes for archive and unarchive are /stop and /start. An archived sandbox needs an explicit /start; commands do not unarchive it. A sleeping sandbox wakes on a command or file operation, whether it was slept by /sleep or by the idle policy. Reboot returns 409 for an archived sandbox; unarchive first. Restart your application’s servers after rebooting. See Recovery for interrupted or unavailable sandboxes.

Fork a sandbox

POST /vms/{id}/branch creates an independent copy and returns 201 with a sandbox object. You may supply a UUID in child_vm_id for retrying a single fork. To request several copies from the same point, send {"count": 4}. Counts from 2 to 16 return {"vms": [...]}. Copies count toward the organization’s sandbox limit. A fork inherits its parent’s datasets; sending dataset or datasets on a fork returns 400. A fork does not inherit its parent’s lifetime: send timeout_s with the fork to give each copy one, or omit it for the platform default. Forks include files and running processes. Fork between commands, and reconnect external services independently in each copy. See Save, restore, fork.

Outbound network policy

PUT /vms/{id}/egress replaces a sandbox’s outbound policy. The body is the whole policy; nothing is merged with the previous one:

Body	Policy
`{"allow_egress": ["pypi.org", "*.githubusercontent.com"]}`	Only the listed destinations.
`{"disable_internet": true}`	No outbound traffic.
`{}`	Open internet access.
`{"allow_egress": ["0.0.0.0/0"]}`	Open internet access, the same as `{}`.

It returns 200 with disable_internet, allow_egress, and applied. applied is false for an archived sandbox, which takes the policy when it is unarchived. Connections the new policy no longer allows are closed. Repeating the same request is safe.

Entry	Example	Allows
Hostname	`pypi.org`	HTTPS and plain HTTP to that name on any TCP port, matched on the TLS server name or `Host` header the client sends.
Wildcard	`*.example.com`	Names below the suffix, not the suffix itself.
IPv4 address or CIDR	`52.0.0.0/8`	Any protocol to those addresses.

URLs, ports, paths, IPv6, a bare *, and private or reserved ranges return 400 naming the entry. DNS in the sandbox answers only listed names. See Limit outbound network access.

Public endpoints

Route	Request or response
`POST /vms/{id}/expose`	Send `{"guest_port": 8000}`. Returns `201` with `ingress_id`, `guest_port`, `public_port`, and `public_url`.
`GET /vms/{id}/ingress`	`{"ingresses": [...]}`
`DELETE /ingress/{id}`	`204`. Remove the endpoint.

Use public_url to access an HTTP server listening on the specified sandbox port. Leave public_port unset or zero to use the assigned port. Anyone with the URL can reach the application, so add authentication where needed. An endpoint on an archived sandbox becomes usable after unarchive. The URL is preserved, but it may briefly return 404 during reconnection. Deleting the sandbox makes the endpoint unavailable. See Expose a web service.

Snapshots and exports

Save and manage snapshots

Route	Request or response
`POST /vms/{id}/snapshot`	Optional `{"leave_paused": false, "snapshot_id": "YOUR_UUID"}` (`leave_paused: true` leaves the sandbox sleeping; the field keeps its historical name). Returns `201` with snapshot information.
`GET /vms/{id}/snapshots`	`{"snapshots": [...]}` for the original sandbox.
`GET /snapshots`	`{"snapshots": [...]}` for the organization.
`GET /snapshots/{id}`	Snapshot object.
`DELETE /snapshots/{id}`	`204`. An in-progress export may prevent deletion.
`GET /snapshots/{a}/diff/{b}`	What changed from snapshot `a` to snapshot `b`: `files`, `processes`, and `memory`. Add `?content=true` for changes inside files and row-level SQLite changes (`databases`). See `diff`.
`POST /vms/{id}/merge`	`{"source": "SNAPSHOT_ID", "base": "SNAPSHOT_ID", "on_conflict": "fail", "dry_run": false}`. Applies the file changes from `base` to `source` to this sandbox. Returns the merge report, with `pre_merge_snapshot_id` when something was applied. See `merge`.

A snapshot object includes snapshot_id, vm_id, parent_snapshot_id, state, durable, image, data_bytes, and created_unix_ns. Poll the snapshot until durable is true before relying on it for recovery or exporting it. data_bytes is the snapshot’s size in real bytes: all of its data, excluding the base image and any dataset. It is 0 until the size has been measured, shortly after the snapshot becomes durable. Storage limits and usage count this size. The original sandbox keeps running unless you request leave_paused=true (the field keeps its historical name). That option leaves it sleeping until the next command or file access, which wakes it automatically. Restore by sending {"snapshot_id": "YOUR_SNAPSHOT_ID"} to POST /vms. Restoring creates a new sandbox; deleting the original does not delete its snapshots.

Export a snapshot

Route	Request or response
`POST /snapshots/{id}/export`	Optional `{"export_id": "YOUR_UUID"}`. Returns `202` with `export_id`. Requires a durable snapshot.
`GET /exports/{id}`	Export status, downloadable `files` when ready, and `error` if failed.
`DELETE /exports/{id}`	`204`. Remove a completed export’s files. Returns `409` while it is pending.

An export moves from pending to ready or failed. When ready, files contains links for memory.img.zst and disk.img.zst compressed with Zstandard, plus state.json and manifest.json metadata. Each file entry includes its name, size, checksum, and download URL. expires_unix gives the export’s expiry time in Unix seconds; download the files before the links expire. Exports are for downloading and inspecting saved data. The API does not import an export to restore a sandbox; use the original snapshot ID for restoration. Deleting the source snapshot does not revoke a completed export. Delete the export separately if you want to remove its files before expiry.

Templates

POST /templates creates a reusable environment. name and image are required; version, cpus, memory_mb, runtime, and disable_internet are optional. A template has no egress allowlist: a non-empty allow_egress returns 400. Send allow_egress with each POST /vms that uses the template, or set it later with PUT /vms/{id}/egress.

{
  "name": "python-workspace",
  "image": "python:3.12-slim",
  "cpus": 2,
  "memory_mb": 2048
}

Route	Response
`POST /templates`	`201` with a template object.
`GET /templates`	`{"templates": [...]}`
`GET /templates/{id}`	Template object.
`DELETE /templates/{id}`	`204`; only templates owned by your organization can be deleted.

Template fields include template_id, name, version, source_image, status, status_detail, runtime, base_snapshot_id, created_unix_ns, and last_used_unix_ns. Wait for status="ready" before creating from the template. If it becomes failed, read status_detail for the reason. The list can include read-only shared templates marked shared=true. You can also look up a shared template ID returned in an image-preparation error. A later create using the same image can retry preparation if a shared template failed.

Registries

POST /registries stores credentials for a registry and returns 204. For a username and token or password, use:

{
  "host": "ghcr.io",
  "kind": "static",
  "username": "YOUR_USERNAME",
  "secret": "YOUR_REGISTRY_TOKEN"
}

For an ECR role, use host, kind="ecr-assume-role", role_arn, and external_id. These credentials apply to your organization’s image pulls.

Route	Response
`GET /registries`	`{"registries": [...]}` with `host`, `kind`, `created_unix_ns`, and `updated_unix_ns`. Secrets are not returned.
`DELETE /registries/{host}`	`204`. Remove the stored credential.

See Private registries for an SDK example that reads credentials from environment variables.

Activity and metrics

Route	Response
`GET /vms/{id}/events?limit=200`	`{"events": [...]}` with `kind`, `detail`, `node`, and `at`, newest first.
`GET /vms/{id}/logs?tail_bytes=65536`	`{"content": "...", "truncated": false}` with system-log output.
`GET /vms/{id}/metrics?since_unix=&max_samples=`	`{"samples": [...], "cpus": n}` with recent resource measurements.
`GET /vms/{id}/metrics/history?hours=24`	`{"points": [...]}` with historical measurements.

Recent samples contain at_unix, interval_s, cpu_ms, mem_mb, rx_bytes, tx_bytes, and state. They cover approximately two hours at 30-second intervals. History uses minute intervals and accepts hours from 1 to 360, or start and end as RFC3339 timestamps, up to 15 days back. A point with measured=false represents a missing measurement. Events and historical metrics can be queried after sandbox deletion within their retention periods. Live logs are unavailable for archived sandboxes; reading logs from a sleeping sandbox does not wake it.

Usage

GET /usage?start=<RFC3339>&end=<RFC3339> returns organization usage, defaulting to the last 24 hours. A query window can cover up to 32 days. The response contains start, end, a states array, and storage totals. An empty states array means no usage was recorded for the window. Each states entry names a state and sums that state’s usage:

Field	Meaning
`vm_seconds`, `cpu_seconds`, `memory_mb_seconds`	Sandbox time, allocated vCPU time, and allocated memory over time, in seconds.
`vm_ms`, `cpu_ms`, `memory_mb_ms`	The same sums in milliseconds.
`cpu_used_vcpu_us`, `cpu_used_process_us`, `cpu_used_guest_us`	CPU actually used, in microseconds.
`net_rx_bytes_exact`, `net_tx_bytes_exact`	Bytes received and sent by the sandbox.
`disk_provisioned_byte_seconds`, `disk_used_byte_seconds`, `disk_used_measured_ms`	Writable disk provisioned and used over time, and how much of the time the used figure covers.

Storage totals are byte-seconds, measured in the real size of your data. Divide one by the window length in seconds for the average size held:

Field	Meaning
`snapshot_storage_byte_seconds`	Data held by your snapshots and archived sandboxes, excluding the base image and any dataset.
`dataset_storage_byte_seconds`	Size of each dataset granted to your organization, for as long as the grant exists.
`export_byte_seconds`	Files of your ready exports.

Real bytes are the only storage size. snapshot_byte_seconds and stored_byte_seconds are deprecated and scheduled for removal; do not build on them. Usage is reported in minute intervals, so short runs and state changes may be grouped within an interval. Deleted snapshots and exports stop accumulating usage. Add key=<API key ID> to /usage, /usage/series, /rated-usage, or /audit to narrow the result to one API key: usage of the sandboxes that key created, or the records of requests it made. Send key= with an empty value for activity no API key carried, such as the console. Omit key for the whole organization. Storage is never attributed to a key. GET /usage/series?hours= or start=&end= returns a time series for activity charts.

Rated usage

GET /rated-usage?start=<RFC3339>&end=<RFC3339> returns your usage priced by hour. It covers closed hourly periods whose start falls in the window, defaulting to the last 24 hours, up to 32 days. The response contains start, end, rows, rate_cards, totals, and closed_through_unix_ns, the end of the last closed hour.

Row field	Meaning
`kind`	`period` for an hour, or `correction` for usage that arrived after its hour closed. Corrections add to their hour; they never replace it.
`period_start_unix_ns`, `period_end_unix_ns`	The UTC hour the row covers.
`rate_card_version`, `storage_model`	The rate card that priced the row and its storage basis.
`cpu_alloc_vcpu_us`, `memory_mib_ms`	Configured vCPU time and allocated memory while running, in vCPU-microseconds and MiB-milliseconds. Sleeping, archived, and every other state are free.
`cpu_vcpu_us`	CPU time your sandboxes actually used. Informational; it is not charged.
`egress_bytes`	Bytes sent.
`snapshot_storage_byte_seconds`, `dataset_storage_byte_seconds`	Billed storage. Each snapshot is free for its first 7 days, and each archived sandbox for the first 7 days after it is archived, so `snapshot_storage_byte_seconds` counts only snapshots and archived sandboxes older than that; Usage reports every byte.
`disk_excess_byte_seconds`	Writable disk above the free allowance per sandbox (the rate card’s `disk_free_bytes`), over time. Counted in every state but archived.
`cpu_nanos`, `memory_nanos`, `storage_nanos`, `egress_nanos`, `disk_nanos`, `total_nanos`	Charges in billionths of a US dollar. `storage_nanos` is the sum of `snapshot_storage_nanos` and `dataset_storage_nanos`. `total_nanos` is every charge: CPU, memory, storage, egress, disk, and the reserved charges.
`reserved_vcpu_us`, `reserved_memory_mib_ms`	Your reserved capacity for the hour, whether or not sandboxes ran.
`covered_cpu_alloc_vcpu_us`, `covered_memory_mib_ms`	The part of the hour’s CPU and memory that the reservation covers: the smaller of usage and reserved capacity. `cpu_nanos` and `memory_nanos` charge only the usage above it.
`reserved_cpu_nanos`, `reserved_memory_nanos`	Charges for the reserved capacity.

totals sums every returned row, corrections included. Each rate_cards entry gives a card’s version, effective_from_unix_ns, storage_model, and its rates; disk_nanos_per_gb_month prices disk above disk_free_bytes per sandbox, and reserved_cpu_nanos_per_vcpu_hour and reserved_memory_nanos_per_gib_hour are null on a card that prices no reservations. reservations lists your reservations active in the window: id, vcpus, memory_mb, starts_at_unix, and ends_at_unix (0 while open-ended). A reservation is billed every hour it is active and doesn’t reserve placement capacity. total_nanos is what your credit balance is charged for the row. GET /rated-usage/keys accepts the same window and returns totals plus a keys array of {"key_id", "totals"}, one per API key that created sandboxes. The keys’ totals sum exactly to totals. Storage and reservations appear under the empty key_id, which also holds usage that no API key carried.

Account

Route	Response
`GET /whoami`	`{"subject", "client", "tier"}`: your organization ID, the ID of the API key that made the request, and the organization’s plan class, such as `open`.
`GET /billing`	`{"frozen", "frozen_since_unix_ns", "reasons"}`. When `frozen` is `true`, new work returns `402`; see Status codes.

Audit

GET /audit?limit=200&before= returns {"records": [...], "next_before": ...}. Records include id, key_id, action, resource, outcome, request_id, and at, newest first. Use next_before as the next request’s before value to continue through older records.

Status codes

Code or error	Meaning	Next action
`202` from `POST /vms/{id}/stop`	The archive is still running.	Poll the sandbox until `state` is `archived`.
`400`	Invalid request or field value.	Check the request body and limits.
`401`	Missing or invalid credentials.	Check the API key.
`403`	Insufficient permission.	Check the key’s organization and access.
`402` with `{"error":"billing","kind":"frozen"}`	The organization is frozen; `reasons` says why. Creates, forks, template builds, and wakes are refused; running sandboxes continue.	Restore billing or contact support. Retrying does not help.
`403` with `{"error":"quota","kind":"cap"}`	Active sandbox limit reached.	Archive or delete an unused sandbox.
`403` with `"kind":"cpu_cap"` or `"kind":"ram_cap"`	The organization’s total vCPU or memory across sandboxes is in use.	Archive or delete a sandbox.
`403` with `"kind":"storage_cap"`	The organization’s snapshot storage is full.	Delete snapshots or archived sandboxes.
`400` with `at most 10 datasets can be attached to one sandbox`, `dataset "<name>" is listed more than once`, `datasets "<a>" and "<b>" are the same data; attach only one of them`, or `send either dataset or datasets, not both`	The `datasets` list is too long or repeats a name, or both fields were sent.	Fix the request body.
`400` with `attaching more than one dataset is not enabled yet`	Several datasets are not yet enabled on the service.	Attach one dataset, or retry later.
`403` naming a dataset	The dataset is not granted to your organization.	Check the name, or contact support.
`404`	Resource not found in the key’s organization.	Check the ID and organization.
`409`	An action conflicts with the resource’s current state.	Read the error and resolve that state before retrying.
`429` with `Retry-After`	Request budget reached.	Wait for the indicated interval, then retry.
`400` starting `allow_egress:`	An allowlist entry is invalid; the message names it.	Fix that entry.
`400` starting `invalid JSON body:`	A field has the wrong type; the message names the field and the type it takes.	Send that type.
`503` from `PUT /vms/{id}/egress`	The policy is recorded but the sandbox’s host has not applied it yet.	Repeat the same request.
`503` with `template_id`	Image preparation is in progress.	Poll the template until ready, then retry the create.
`503` with `{"error":"capacity","kind":"placement"}`	Capacity is temporarily unavailable.	Retry with backoff; respect `Retry-After` when provided.
`503` with `sandbox agent unreachable`	The sandbox is unresponsive.	Try rebooting to retain files, or delete and recreate it.
`503` naming a dataset	No host that can run the sandbox currently holds the dataset.	Retry after a short wait; if it persists, contact support.
`503` with `no host currently holds all of the datasets ...; retry shortly`	No host currently holds every requested dataset.	Retry after a short wait; if it persists, contact support.
`503` with `this host's guest image does not support multiple datasets`	The create reached a host not yet updated for several datasets; nothing was created.	Retry later; if it persists, contact support.
Other `5xx`	The service could not complete the request.	Check the resource state before retrying a change whose outcome is unknown.

Common 409 messages include sandbox is archived (sandbox is stopped) (unarchive first), sandbox is busy (a sleep was refused because running work keeps the sandbox awake), a template that is not ready, or a snapshot with an export in progress. A checkpoint attempt on an unresponsive sandbox can also return 409 with sandbox agent unreachable. Match errors on the SDK’s typed exceptions — SandboxArchivedError for the archived refusal — rather than on message text. Message wording can change; the state names reported by the API do not. If you must inspect the text, match archived. Follow Retry-After for rate-limited requests. x-ratelimit-* headers are advisory and describe the budget observed by that response. DELETE requests are exempt from rate limits. See Request rates.

Getting Started

Reference

Guides

Authentication

Sandboxes

Create a sandbox

Find or delete sandboxes

Run a command

Keep a shell session

Lifecycle actions

Fork a sandbox

Outbound network policy

Public endpoints

Snapshots and exports

Save and manage snapshots

Export a snapshot

Templates

Registries

Activity and metrics

Usage

Rated usage

Account

Audit

Status codes

​Authentication

​Sandboxes

​Create a sandbox

​Find or delete sandboxes

​Run a command

​Keep a shell session

​Lifecycle actions

​Fork a sandbox

​Outbound network policy

​Public endpoints

​Snapshots and exports

​Save and manage snapshots

​Export a snapshot

​Templates

​Registries

​Activity and metrics

​Usage

​Rated usage

​Account

​Audit

​Status codes

Authentication

Sandboxes

Create a sandbox

Find or delete sandboxes

Run a command

Keep a shell session

Lifecycle actions

Fork a sandbox

Outbound network policy

Public endpoints

Snapshots and exports

Save and manage snapshots

Export a snapshot

Templates

Registries

Activity and metrics

Usage

Rated usage

Account

Audit

Status codes