Use a dataset

A dataset is a read-only collection of files that LithosBox grants to your organization. Name it when you create a sandbox, and the sandbox sees its files at /datasets/<name>. The data is attached to the sandbox rather than copied into its writable disk, so a large dataset does not use your 16 GiB (or larger) disk. LithosBox grants datasets to organizations. Organizations enabled for upload can publish their own (below); otherwise, to request a dataset, contact support. The SDK’s dataset argument requires version 0.7.1 or later; upload requires 0.7.2.

from lithosbox import LithosBox

box = LithosBox()
sandbox = box.sandboxes.create(image="python:3.12-slim", dataset="YOUR_DATASET")
print(sandbox.info.dataset)
print(sandbox.run("ls -la /datasets/YOUR_DATASET").check().stdout)

sandbox.info.dataset names the attached dataset, or is an empty string when the sandbox has none. Omit image to use the default environment with the dataset.

Upload your own

For organizations enabled for upload (others get FeatureNotEnabledError, 403). Files go straight from your machine to storage; the platform then builds the dataset, stages it on every host, and grants it to your organization.

ds = box.datasets.create("parquet-2026-10-01")   # names: lowercase, digits, . _ -
ds.upload("/data/parquet")                        # parallel; re-run to resume
ds.publish()
ds.wait()                                         # uploading > building > pinning > ready
sandbox = box.sandboxes.create(dataset=ds.name)

Or from a shell: lithosbox datasets upload /data/parquet --name parquet-2026-10-01 (then lithosbox datasets status NAME / list). Only regular files are uploaded (symlinks are refused) and the folder layout is kept under /datasets/<name>/. A published dataset does not change: new data is a new name.

Create over HTTP

Send dataset with POST /vms:

curl -fsS https://api.sandbox.lithosai.cloud/vms \
  -H "Authorization: Bearer $LITHOSBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "python:3.12-slim", "dataset": "YOUR_DATASET"}'

The sandbox object includes a dataset field when a dataset is attached; the field is absent otherwise. See Create a sandbox.

Read dataset files

Process dataset files inside the sandbox with run() and return only the results. The tools you use, such as DuckDB or pandas, come from your image:

result = sandbox.run(
    "df -h /datasets/YOUR_DATASET && ls /datasets/YOUR_DATASET | head"
)
print(result.check().stdout)

sandbox.files.read() runs inside the sandbox too, but returns at most about 16 MiB of text (12 MiB with read_bytes()) per call. It suits small files such as a README or manifest, not dataset contents. Write outputs to a writable path such as /work; see Work with files to download them. The mount is read-only. Writing, deleting, or renaming anything under /datasets fails with Read-only file system.

Forks, snapshots, and archives

A dataset stays with the sandbox and everything made from it:

Forks inherit the parent’s dataset. A fork request cannot name a dataset; over HTTP, sending dataset to /branch returns 400.
Snapshots record the dataset, and a restore mounts it again. Only your organization can restore such a snapshot, and only while the dataset is still granted to your organization at the same version; otherwise the restore returns 403.
Archive and unarchive keep the dataset attached.

A snapshot does not include the dataset’s files, so the dataset adds nothing to your snapshot storage.

Limits and errors

A sandbox can have one dataset, chosen at creation. It cannot be added to or removed from an existing sandbox.
Dataset names use lowercase letters, digits, ., _, and -, start with a letter or digit, and are at most 64 characters.
dataset cannot be combined with template or snapshot_id, and templates cannot include a dataset. Datasets work with image or the default image.
A create with a dataset always starts its image fresh rather than from a prepared template, so it takes longer than other creates.

Error	Cause	What to do
`ValueError` (SDK), `InvalidRequestError`, or `400`	`dataset` combined with `template` or `snapshot_id`, an invalid name, or `dataset` sent to a fork or template.	Remove the conflicting field.
`AuthError` / `403`	The dataset is not granted to your organization, or a snapshot’s dataset is no longer granted at that version.	Check the name, or contact support.
`ServerError` / `503` naming the dataset	No host that can run the sandbox currently holds the dataset.	Retry after a short wait. If it persists, contact support.

Usage

Your organization’s usage reports each granted dataset’s size as dataset_storage_byte_seconds, for as long as the grant exists, whether or not a sandbox is using it. The console’s usage view shows it as Dataset storage. See Usage for the fields. When finished:

sandbox.delete()
box.close()

Deleting the sandbox does not remove the dataset or its grant.

Getting Started

Reference

Guides

Upload your own

Create over HTTP

Read dataset files

Forks, snapshots, and archives

Limits and errors

Usage

​Upload your own

​Create over HTTP

​Read dataset files

​Forks, snapshots, and archives

​Limits and errors

​Usage

Upload your own

Create over HTTP

Read dataset files

Forks, snapshots, and archives

Limits and errors

Usage