Limits and behavior

Sandbox resources

Resource	Limit	When reached
Active sandboxes per organization	5; includes creating, running, sleeping, and waking sandboxes, not archived ones	Create, fork, or unarchive returns `403` with `kind="cap"`. Archive or delete an unused sandbox.
Storage per organization	150 GB (10⁹ bytes) of real data in snapshots and archived sandboxes	Snapshot, fork, or template build returns `403` with `kind="storage_cap"`. Delete snapshots or archived sandboxes.
CPU	1–4 vCPU per sandbox; default 2	An invalid value returns `400`.
Memory	128–8192 MiB per sandbox; default 1024	An invalid value returns `400`.
Writable disk	16 GiB (default) or 32 GiB; 64 GiB on upgraded plans	Any other `writable_size_bytes` value returns `400`. The disk can grow when restoring a snapshot, never shrink; fork copies always inherit the parent’s size.
Fork copies	Up to 16 per call, within the organization limit	Reduce the count or free active sandbox slots.
Datasets	Up to 10 per sandbox, each granted to your organization and mounted read-only at `/datasets/<name>`; fixed at creation	More than 10, or a repeated name, returns `400`; an ungranted name returns `403`. See Datasets.
Lifetime (`timeout_s`)	Optional; none by default. Whole seconds up to 3,153,600,000 (100 years), fixed at creation	Any other value returns `400`. See Set a lifetime.
Shell sessions	256 concurrent per sandbox	Opening another session returns `409`. Close unused sessions.
GPU	Not yet supported	Use CPU-compatible workloads.

Templates and snapshots retain their CPU and memory configuration when used to create another sandbox. A snapshot also records its writable-disk size: a restore may request a larger size from the allowed set, but never a smaller one, and a fork accepts no size at all — see Grow the writable disk. Sleeping does not release an active sandbox slot; archiving does.

Organization quotas

An organization can also have quotas on its total resources. Each refusal is a 403 with {"error":"quota"} and a kind:

`kind`	Quota	How to free it
`cap`	Active sandbox count, above	Archive or delete a sandbox.
`cpu_cap`, `ram_cap`	Total vCPU or memory across active sandboxes; sleeping sandboxes keep holding it	Archive or delete a sandbox.
`storage_cap`	Snapshot storage, including archived sandboxes	Delete snapshots or archived sandboxes. Archiving adds storage.

An organization whose billing is frozen receives 402 with {"error":"billing","kind":"frozen"} for creates, forks, template builds, and wakes. Running sandboxes keep running and nothing is deleted. Restore billing or contact support; retrying does not help.

Commands and files

Input or output	Limit	How to work within it
One command argument	131,071 bytes; no NUL characters	Send data through `stdin` or a file.
Standard input	4 MiB per call	Transfer larger inputs in chunks or download inside the sandbox.
Standard output and error	Up to 16 MiB each	Lower on sandboxes below 1 GiB RAM; JSON-escaped text can reach the limit sooner. Check `ExecResult.truncated`; save larger results to files.
Synchronous command	About 110 seconds, including session commands	Use `background=True` and collect results later.
`files.write()`	4 MiB; replaces the whole file	Use an append command for chunks, not repeated writes.
`files.read()`	Approximately 16 MiB of text	Transfer larger files through another method.
`files.read_bytes()`	Approximately 12 MiB	Transfer larger files through another method.
Snapshot diff	120 seconds per request; more than about 2 GiB of changed disk fetched from storage can exceed it	Diff nearer snapshots.
Merge content	256 MiB of file content per merge	Merge from a snapshot with fewer large files, or move large files another way.
System log read	256 KiB per call	Request the tail you need.

Command output is UTF-8 text; invalid sequences are replaced. Use read_bytes() for binary files. See Run commands and Work with files for examples.

Processes and memory

For the default runtime, the process limit is one process per MiB of configured memory, with a minimum of 256 and a maximum of 4096. At the default 1 GiB, that allows 1024 processes. The vm runtime allows four per MiB, with a minimum of 1024 and a maximum of 16,384. At the process limit, new processes may fail to start with EAGAIN. An execution that creates too many processes can be terminated. Reduce concurrency or choose more memory. If the sandbox becomes unresponsive, reboot it or create a new one. In the default runtime, application memory is the configured memory minus a reserve of the greater of 128 MiB or 10%. For configurations below 256 MiB, half the memory is available to applications. Processes that exceed the available memory may be terminated. Account for that allowance when choosing memory for a workload.

Request rates

The default request budgets are per organization:

Request group	Requests per minute
Creates, restores, snapshots, forks, public endpoints, templates, and exports	300
Other operations, including commands and reads	12,000
DELETE requests	Exempt from rate limits

A 429 response includes Retry-After. Wait for that interval before retrying. Rate-limit headers describe the budget observed by that response; they are advisory, not an exact counter of what another concurrent request can use. In the SDK, a rate limit is QuotaError(kind="rate"). It differs from QuotaError(kind="cap"), which requires releasing a sandbox slot, and CapacityError, which indicates temporarily unavailable capacity. See HTTP status codes.

Waits and time ranges

Operation	Default or maximum
Ordinary SDK request	120-second timeout
Create request	At least a 300-second SDK timeout
Wait for image preparation	900 seconds; configure `warm_timeout` on `create()`
Wait for snapshot durability	120 seconds; configure `timeout`
Wait for a template or export	900 seconds; configure `timeout`
Recent metrics	Approximately 2 hours at 30-second intervals
Historical metrics	Up to 15 days, in minute intervals
Organization usage query	Up to a 32-day window

A timeout while waiting does not cancel image preparation, saving, or export. Check the resource’s status before retrying. If a create loses its response, inspect the sandbox list before issuing a new create.

Networking

Outbound connectivity uses IPv4. Access to link-local addresses (169.254.0.0/16) is blocked. Set disable_internet=True when creating a sandbox to disable outbound internet access; forks and snapshot restores keep that setting. allow_egress limits a sandbox to a list of destinations: up to 256 hostnames, *. wildcards, and public IPv4 addresses or CIDRs. Hostname entries cover HTTPS and plain HTTP; other protocols need an address or CIDR entry. Forks, snapshot restores, and unarchive keep the list. See Limit outbound network access. A blocked outbound connection can wait until the application’s own timeout. Set finite connection timeouts in applications that may run without internet access. Public endpoints accept HTTP/1.1 and HTTP/2 and require application authentication if the content should be private. See Expose a web service.

Lifecycle behavior

Idle sandboxes can sleep about 60 seconds after their last activity: the end of the last command or file operation, or the last moment they were doing work. Work keeps them awake: CPU use, open connections, and processes waiting on a timer. Background processes that are only waiting, and exposed services with no traffic, sleep with the sandbox and resume when it wakes. Running a command, accessing a file, or a request to an exposed port wakes a sleeping sandbox. Archived sandboxes require an explicit unarchive. Files, including files in /tmp, survive archive/unarchive and reboot. Reboot ends processes and sessions. Delete removes the sandbox’s working state; retained snapshots must be deleted separately. See Manage sandbox lifecycle.

Harbor benchmarks

The LithosBox Harbor provider runs benchmark tasks in sandboxes. In your existing Harbor Python environment, install the provider:

python -m pip install https://get.sandbox.lithosai.cloud/sdk/lithosbox_harbor-0.1.0-py3-none-any.whl

Add --env lithosbox_environment:LithosBoxEnvironment to your Harbor run command. Provide LITHOSBOX_TOKEN through that environment’s secret configuration and set LITHOSBOX_API_URL=https://api.sandbox.lithosai.cloud. To prepare a list of images before a run, put one image reference on each line of images.txt, then run:

python -m lithosbox_prebuild images.txt

Getting Started

Reference

Guides

Limits and behavior

Sandbox resources

Organization quotas

Commands and files

Processes and memory

Request rates

Waits and time ranges

Networking

Lifecycle behavior

Harbor benchmarks

​Sandbox resources

​Organization quotas

​Commands and files

​Processes and memory

​Request rates

​Waits and time ranges

​Networking

​Lifecycle behavior

​Harbor benchmarks

Sandbox resources

Organization quotas

Commands and files

Processes and memory

Request rates

Waits and time ranges

Networking

Lifecycle behavior

Harbor benchmarks