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`	OAuth client credentials, for accounts configured to use them. 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.
`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`	Fixed at 16 GiB	Other sizes are rejected.

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. 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) 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.

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. See Run commands.

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. 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 names in a directory.
`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 in the console or with GET /vms/{id}/ingress. See Expose a web service for a complete example.

Lifecycle and checkpoints

Method	Behavior
`sandbox.sleep()`	Park the sandbox and return whether it slept. Commands and file access wake it transparently; a busy sandbox stays awake.
`sandbox.wake()`	Wake a sleeping sandbox eagerly, ahead of a burst. Any command wakes it anyway.
`sandbox.pause()` / `sandbox.resume()`	Aliases for `sleep()` / `wake()`.
`sandbox.archive()` / `sandbox.unarchive()`	Save the sandbox for later, release its active slot, and resume it explicitly.
`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_paused=False, wait_durable=False, timeout=120) Returns SnapshotInfo, including id, vm_id, state, and durable. The sandbox keeps running by default. leave_paused=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
`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) Without n, return one independent Sandbox. With n, return a list of that many copies; n=1 returns a one-element list. Up to four copies can be requested at once. Copies include files and running processes. Fork between commands and reconnect external services independently in each copy. 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.
`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.
`NotFoundError`	Check that the resource ID exists in your organization.
`SandboxPausedError`	Call `resume()` before running commands.
`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.
`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.
`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.

Error classes are available from lithosbox.errors. API errors expose status and body where a response is available. SandboxPausedError and SandboxStoppedError are subclasses of ConflictError. 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

Concepts

Configure the client

Create and find sandboxes

create

Commands, sessions, and files

run

session

files

Public endpoints

Lifecycle and checkpoints

snapshot

fork

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

​Lifecycle and checkpoints

​snapshot

​fork

​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

Lifecycle and checkpoints

snapshot

fork

Activity, logs, and metrics

Templates, registries, and exports

Errors