Python SDK

Use the Python SDK from an environment configured by the installer. The examples below use box for the client and sandbox for a sandbox returned by box.sandboxes.create() or box.sandboxes.get().

Configure the client

from lithosbox import LithosBox

box = LithosBox()

Run scripts with lithosbox python to use the key you saved during installation. For other Python environments, provide LITHOSBOX_TOKEN through the environment or pass token= to the client. Keep credentials outside your source code.

Argument	Purpose
`token`	API key or bearer token; defaults to `LITHOSBOX_TOKEN`.
`api_url`	API address; can also be set with `LITHOSBOX_API_URL`.
`timeout`	Request timeout in seconds; defaults to 120. Create requests allow at least 300 seconds.
`auth_url`, `client_id`, `client_secret`	Alternative sign-in for deployments that authenticate service accounts through an OIDC provider instead of API keys (the client fetches and refreshes a bearer token itself). Ordinary accounts do not use these — an API key via `token` is the standard path. Corresponding `LITHOSBOX_AUTH_URL`, `LITHOSBOX_CLIENT_ID`, and `LITHOSBOX_CLIENT_SECRET` variables are supported.

Keep a client open while you use its sandbox handles. Call box.close() when finished, or use with LithosBox() as box:. Closing the client does not delete its sandboxes. For asynchronous code, use AsyncLithosBox, async with, and await:

import asyncio
from lithosbox import AsyncLithosBox

async def main():
    async with AsyncLithosBox() as box:
        async with await box.sandboxes.create() as sandbox:
            result = await sandbox.run(["python3", "-c", "print(42)"])
            print(result.check().stdout)

asyncio.run(main())

Create and find sandboxes

create

box.sandboxes.create() Returns a Sandbox. Choose at most one of image, template, or snapshot_id. Omit all three to use the default environment.

Argument	Default	Purpose
`image`	None	OCI image reference.
`template`	None	Template ID, name, or `name:version`.
`snapshot_id`	None	Snapshot to restore into a new sandbox.
`cpus`	2 for an image create	CPU count, from 1 to 4.
`memory_mb`	1024 for an image create	Memory in MiB, from 128 to 8192.
`runtime`	`container` for an image create	`container` or `vm`; see Custom images.
`disable_internet`	`False`	Disable outbound internet access.
`allow_egress`	None	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. See Limit outbound network access. SDK 0.10.0 and later.
`timeout_s`	None	Lifetime in whole seconds: the sandbox is deleted that long after it was created, whatever its state. Omit for the platform default (no lifetime); `0` asks for none. See Set a lifetime. SDK 0.10.2 and later.
`wait_for_template`	`True`	Wait for image preparation; otherwise raise `TemplateBuildingError`.
`warm_timeout`	900	Maximum time in seconds to wait for image preparation.
`writable_size_bytes`	16 GiB	Writable disk size in bytes: 16 or 32 GiB (64 GiB on upgraded plans). On a snapshot restore it may only grow; not accepted on fork.
`dataset`	None	Name of a read-only dataset granted to your organization, mounted at `/datasets/<name>`. Works with `image` or the default image; cannot be combined with `template` or `snapshot_id`. SDK 0.7.1 and later.
`datasets`	None	List of up to 10 distinct dataset names, each mounted at `/datasets/<name>` in order. Same rules as `dataset`; pass one of `dataset` or `datasets`. More than 10, a repeated name, or both arguments raise `ValueError` before any request. SDK 0.7.4 and later.

Template and snapshot creates use the source’s CPU and memory configuration. The SDK reuses the same sandbox ID during retries within a create call. If a call fails without a response, inspect existing sandboxes before making a new create call.

Method	Result
`box.sandboxes.get(id)`	A `Sandbox` for an existing ID.
`box.sandboxes.list()`	List of the organization’s sandboxes.
`box.sandboxes.delete(id)`	Delete a sandbox. Repeating deletion is safe.
`sandbox.refresh()`	Refresh `sandbox.info` and return the handle.

A handle exposes sandbox.id and sandbox.info, including its state, image, CPU, and memory configuration. sandbox.info.datasets lists the attached datasets in order (an empty list when there are none); sandbox.info.dataset is the first, or an empty string. sandbox.info.allow_egress lists the sandbox’s allowed destinations (an empty list when it has none). sandbox.info.timeout_s and sandbox.info.expires_unix_ns report its lifetime and when it ends (both 0 when it has none). with box.sandboxes.create() as sandbox: deletes the sandbox when the block ends.

Commands, sessions, and files

run

sandbox.run(command, *, background=False, stdin=None, stream=False, timeout=None) Returns an ExecResult with stdout, stderr, and exit_code. Call .check() to raise on a nonzero exit code. stdout_truncated, stderr_truncated, and truncated indicate output limits were reached.

Argument	Default	Purpose
`command`	Required	Shell string with pipes, redirects, and variable expansion, or a list of literal string arguments. Use a list for user-provided values.
`background`	`False`	Wait for the command to finish. Set to `True` to start a server or worker and return after it starts; requires a shell string.
`stdin`	`None`	Send bytes or text to the command’s standard input, up to 4 MiB. Cannot be combined with `background=True`; write input to a file first.
`stream`	`False`	Return an `ExecStream` at once instead of waiting: iterate it for `ExecEvent`s while the command runs, with no time limit.
`timeout`	`None`	With `stream=True`, stop the command after this many seconds.

With background=True, the result reports startup status. No process ID is returned. Redirect output to a file and check the job’s eventual exit status separately. Foreground completion does not guarantee every child process has exited. Use background mode explicitly for servers and workers. Synchronous commands allow about 110 seconds; each output stream is limited to 16 MiB. Sandboxes below 1 GiB RAM can truncate earlier, as can text that expands when JSON-encoded. Check the truncation flags before using the result. See Run commands. With stream=True, iterate the returned ExecStream (async for on AsyncSandbox). Each ExecEvent has a kind: output (fd is stdout or stderr, data is raw bytes, seq and ts order it), gap (output the sandbox dropped before this reader asked for it, seq through gap_to), and finally exit (exit_code, reason: exited, killed, timeout, oom, sandbox_gone or lost). The stream reconnects on its own. stream.kill() stops the command; stream.exec_id and stream.next_seq let sandbox.exec(exec_id=..., from_seq=..., stream=True) resume it elsewhere. sandbox.exec(args, stream=True) is the argument-list form.

session

sandbox.session(session_id=None) Returns a Session that keeps its working directory, environment variables, and shell state between commands.

Argument	Default	Purpose
`session_id`	`None`	Choose a shell ID. `None` generates a new ID; reusing an ID shares its shell within this sandbox. The returned handle exposes `session.id`.

Method	Behavior
`run(command)`	`command` is a required shell string. Run it in this session and return an `ExecResult`. Does not accept an argument list, `background`, or `stdin`.
`close()`	Close the shell. Further `run()` calls on this handle raise `ConflictError`.

Use with sandbox.session() as session: to close the shell when the block ends. In the async client, session() is the one factory you do not await — create() is awaited, session() is not, and the session’s own calls are:

sandbox = await box.sandboxes.create()
async with sandbox.session() as session:
    result = await session.run("cd /work && ls")

Handles using the same session ID share that shell; closing one ends it for all handles. An individual session command has the same timeout as sandbox.run(). A sandbox supports up to 256 concurrent sessions. See Keep shell state for an example.

files

sandbox.files

Method	Behavior
`write(path, data)`	Write bytes or text, replacing any existing file. Create missing parent directories.
`read(path)`	Read a text file.
`read_bytes(path)`	Read a binary file.
`list(path=".")`	List a directory. Returns bare names, not full paths; join with the directory you passed.
`exists(path)`	Return whether a path exists.
`mkdir(path)`	Create a directory and missing parents.
`rename(src, dst)`	Move or rename a path.
`remove(path)`	Delete a file or directory, recursively for directories.

Writes allow up to 4 MiB per call. Reads allow approximately 16 MiB of text or 12 MiB of binary data. Use larger-file transfers for files beyond those limits. write() does not append.

Public endpoints

sandbox.expose(port, public_port=None) returns IngressInfo. Its id identifies the endpoint and its url is the public HTTPS address. Use the assigned public port by leaving public_port unset. Start an HTTP server on the specified sandbox port before using the URL. Remove an endpoint with box.ingress.delete(endpoint.id). List endpoints with sandbox.ingress() (SDK 0.6.9 and later), in the console, or with GET /vms/{id}/ingress. See Expose a web service for a complete example.

Outbound network

set_egress

sandbox.set_egress(*, disable_internet=False, allow_egress=None) Replaces the sandbox’s outbound network policy and returns the refreshed handle. The arguments are the whole policy; nothing is merged with the previous one.

Call	Policy
`sandbox.set_egress(allow_egress=["pypi.org"])`	Only the listed destinations.
`sandbox.set_egress(disable_internet=True)`	No outbound traffic.
`sandbox.set_egress()`	Open internet access.
`sandbox.set_egress(allow_egress=["0.0.0.0/0"])`	Open internet access, the same as `set_egress()`.

Connections the new policy no longer allows are closed. An archived sandbox applies the policy when it is unarchived. Entries follow the same rules as create(allow_egress=...); an invalid entry raises InvalidRequestError naming it. SDK 0.10.0 and later. See Limit outbound network access.

Lifecycle and checkpoints

Method	Behavior
`sandbox.sleep()`	Park the sandbox and return whether it slept. ANY command or file access wakes it transparently — there is no wake method. A busy sandbox stays awake.
`sandbox.archive()` / `sandbox.unarchive()`	Save the sandbox for later, release its active slot, and bring it back explicitly. An archive that takes longer than about 110 seconds keeps running after the call returns; `sandbox.info.state` then reads `archiving` until it finishes.
`sandbox.reboot()`	Restart the environment, preserving files but ending processes and sessions. Return the refreshed handle.
`sandbox.delete()`	Delete the sandbox. Retained snapshots remain.

See Manage sandbox lifecycle for when to use each action.

snapshot

sandbox.snapshot(*, leave_asleep=False, wait_durable=False, timeout=120) Returns SnapshotInfo, including id, vm_id, state, and durable. The sandbox keeps running by default. leave_asleep=True lets it rest after the checkpoint; the next command or file operation wakes it automatically. Use wait_durable=True to wait until saving completes, with timeout in seconds. A timeout does not cancel saving. Restore with box.snapshots.restore(snapshot); it accepts either a snapshot object or its ID and returns a new Sandbox.

Method	Result
`sandbox.snapshots()`	List this sandbox’s snapshots.
`box.snapshots.list()`	List of organization snapshots.
`box.snapshots.get(id)`	Current `SnapshotInfo`.
`box.snapshots.wait_durable(id, timeout=120)`	Wait for a durable snapshot and return its updated information.
`box.snapshots.delete(id)`	Delete a snapshot. An in-progress export can prevent deletion.

fork

sandbox.fork(n=None, *, timeout_s=None) Without n, return one independent Sandbox. With n, return a list of that many copies; n=1 returns a one-element list. Up to 16 copies can be requested at once. timeout_s gives each copy its own lifetime; a copy never takes its parent’s (SDK 0.10.2 and later). Copies include files and running processes. Fork between commands and reconnect external services independently in each copy. See Save, restore, fork.

diff

box.snapshots.diff(a, b, *, content=False) Returns what changed from snapshot a to snapshot b (snapshot objects or IDs). It is read from the two snapshots, so nothing runs in either sandbox and either may already be deleted. Use any two of your snapshots: before and after a step, two forks, or two different sandboxes.

Key	Contents
`files`	One entry per changed path: `path`, `change` (`added`, `deleted`, `modified`, or `renamed`, with `from` naming the old path), and `a` / `b` with each side’s type, mode, owner, and size.
`processes`	`started`, `exited`, and `changed` processes, with command line, working directory, listening ports, and the memory each one rewrote.
`memory`	Pages and bytes of memory rewritten.
`databases`	With `content=True`: row-level changes in SQLite databases, per table (`counts` of inserted, deleted, and updated rows; up to 1,000 rows of each).

With content=True, modified files also carry content: unified-diff hunks for text, changed_ranges for binary files. A diff usually takes under 3 seconds. A 409 saying a snapshot must finish uploading means it is not yet reachable where the diff runs; retry in a few seconds. A diff that has to fetch more than about 2 GiB of changed disk from storage (the two snapshots on different hosts, or on none) can run past the 120-second request limit; diff nearer snapshots.

merge

sandbox.merge(source, base, *, on_conflict="fail", dry_run=False) Applies to this running sandbox the file changes that turned snapshot base into snapshot source, compared three ways with the sandbox’s own changes since base. It merges files: contents, directories, symlinks, mode, and owner. It does not merge memory or processes. A path changed differently on both sides is a conflict; files merge whole, and a SQLite database is one file. on_conflict="fail" applies nothing if there is any conflict, "skip" applies everything else, and "theirs" takes the source’s version. dry_run=True returns the plan and changes nothing. The sandbox is snapshotted before anything changes. When something was applied, the report’s pre_merge_snapshot_id restores the sandbox to undo the merge.

Key	Contents
`applied`	Whether the changes were applied.
`conflicts`	`path`, `reason`, and the `source` and `target` versions.
`ops`, `counts`	The planned or applied operations.
`same`	Paths both sides changed the same way.
`content_bytes`	File content the merge writes.
`error`	With `applied: False`, the apply stopped part way: restore `pre_merge_snapshot_id`.

A merge writes at most 256 MiB of file content; a larger one returns 409. Hard links arrive as separate copies, modification times become the time of the merge, and extended attributes and sparse holes are not kept. See Save, restore, fork.

Activity, logs, and metrics

Method	Result
`sandbox.events(limit=200)`	List of events, newest first, with `kind`, `detail`, `node`, and `at`.
`sandbox.logs(tail_bytes=65536)`	Text from system logs; at most 256 KiB per call.
`sandbox.metrics(since_unix=0, max_samples=0)`	Recent resource samples in `{"samples": [...], "cpus": n}`.
`sandbox.metrics(hours=24)`	Historical points in `{"points": [...]}`.
`sandbox.metrics(start=..., end=...)`	History for an RFC3339 time range, up to 15 days back.
`box.usage(start=None, end=None)`	Organization resource usage, defaulting to the last 24 hours. See Usage for the fields.
`box.audit(limit=200, before=None)`	Audit records and `next_before` for pagination.

Recent metrics cover approximately two hours at 30-second intervals. Historical metrics use minute intervals and remain available for archived and deleted sandboxes. measured=false identifies a missing measurement. System logs and recent metrics are unavailable while archived. Recent CPU samples report milliseconds used over interval_s. Divide cpu_ms by interval_s * 1000 * cpus for a fraction of allocated CPU capacity. Historical points use util_seconds for the measured duration; do not assume every point contains a full minute of measurements. See Monitor and troubleshoot for examples.

Templates, registries, and exports

Method	Purpose
`box.templates.create(name=..., image=..., ...)`	Create a named template. Optional `version`, `cpus`, `memory_mb`, `runtime`, and `disable_internet` configure it.
`box.templates.build(image, ...)`	Prepare or reuse a template, waiting by default. Supports `name`, `cpus`, `memory_mb`, `runtime`, `wait`, and `timeout`.
`box.templates.list()` / `get(id)` / `delete(id)`	Manage templates. Shared templates are read-only.
`box.templates.wait(id, timeout=900)`	Wait until a template is ready, or raise if it fails.
`box.registries.put(host=..., username=..., password=...)`	Store a private registry credential. Arguments are keyword-only.
`box.registries.list()` / `delete(host)`	List registry metadata or remove a credential.
`box.snapshots.export(snapshot.id)`	Start an export of a durable snapshot. Return `ExportInfo`.
`box.exports.get(id)` / `wait(id, timeout=900)`	Get export status or wait for downloadable files.
`box.exports.delete(id)`	Delete a completed export’s files.

Registry credentials can also use secret= or ECR role settings: kind="ecr-assume-role", role_arn, and external_id. Export file links are temporary; download before their expiry. See HTTP API for export fields. Existing aliases include exec, exec_background, stop/start, branch, and files.ls. The guides use run, archive/unarchive, fork, and files.list.

Errors

Error	What to do
`InvalidRequestError`	Check the arguments and resource limits.
`AuthError`	Check the key, organization, and permissions. Also raised when a dataset is not granted to your organization.
`NotFoundError`	Check that the resource ID exists in your organization.
`SandboxStoppedError`	Call `unarchive()` before running commands.
`ConflictError`	Read the message and resolve the conflicting state before retrying.
`TemplateBuildingError`	Wait for the identified template. `create()` normally handles this automatically.
`TemplateBuildFailed`	Inspect the template’s `status_detail` and correct the image or configuration.
`QuotaError` with `kind="rate"`	Wait for `retry_after` before retrying.
`QuotaError` with `kind="cap"`	Archive or delete an unused sandbox to free a slot.
`QuotaError` 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; sleeping sandboxes keep holding it.
`QuotaError` with `kind="storage_cap"`	The organization’s snapshot storage is full. Delete snapshots or archived sandboxes; archiving adds storage rather than freeing it.
`OrganizationFrozenError`	The organization is frozen; `reasons` names why, for example `credit_exhausted`. Creating, forking, building templates, and waking a sleeping or archived sandbox are refused. Running sandboxes keep running and nothing is deleted. Retrying does not help; restore billing or contact support, and the next call succeeds.
`CapacityError`	Capacity is temporarily unavailable. Retry with backoff and respect `retry_after` when supplied.
`SandboxUnhealthyError`	Try rebooting to keep files, or delete and recreate the sandbox.
`TruncatedReadError`	The file exceeds the read limit. Use larger-file transfers.
`WaitTimeout`	Check the operation’s status; it may still be in progress.
`ExportFailed`	Inspect the export’s `error` field.
`TransportError` or `ServerError`	The outcome may be unknown. Check resources before repeating an action that creates or changes them.
`ClientClosedError`	Create a new client before making more calls.

OrganizationFrozenError and the cpu_cap, ram_cap, and storage_cap kinds require SDK 0.7.1 or later. Earlier versions raise a plain LithosBoxError with status 402 for a frozen organization and report every 403 quota as kind="cap". SandboxStoppedError subclasses ConflictError; SandboxUnhealthyError subclasses ServerError, so a broad except ServerError catches it. Error classes are available from lithosbox.errors. API errors expose status and body where a response is available. SandboxStoppedError is a subclass of ConflictError and the same class as SandboxArchivedError. box.rate.acquire and box.rate.ops expose rate-limit information from the client’s recent responses. They may be None before the first response. Treat the values as advisory and follow retry_after on rate-limit errors. See Limits and HTTP status codes.

Getting Started

Reference

Guides

Configure the client

Create and find sandboxes

create

Commands, sessions, and files

run

session

files

Public endpoints

Outbound network

set_egress

Lifecycle and checkpoints

snapshot

fork

diff

merge

Activity, logs, and metrics

Templates, registries, and exports

Errors

​Configure the client

​Create and find sandboxes

​create

​Commands, sessions, and files

​run

​session

​files

​Public endpoints

​Outbound network

​set_egress

​Lifecycle and checkpoints

​snapshot

​fork

​diff

​merge

​Activity, logs, and metrics

​Templates, registries, and exports

​Errors

Configure the client

Create and find sandboxes

create

Commands, sessions, and files

run

session

files

Public endpoints

Outbound network

set_egress

Lifecycle and checkpoints

snapshot

fork

diff

merge

Activity, logs, and metrics

Templates, registries, and exports

Errors