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.3; several datasets per sandbox (datasets) require 0.7.4.

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.

Attach several datasets

A sandbox can mount up to 10 datasets. Pass a list with datasets; each one is mounted read-only at its own /datasets/<name>:

sandbox = box.sandboxes.create(datasets=["DATASET_A", "DATASET_B"])
print(sandbox.info.datasets)   # ["DATASET_A", "DATASET_B"], in the order given

sandbox.info.datasets lists every attached dataset in order (an empty list when there are none); sandbox.info.dataset is the first. Send either dataset or datasets, not both.

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, or datasets for several, 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"}'

{"image": "python:3.12-slim", "datasets": ["DATASET_A", "DATASET_B"]}

The sandbox object includes datasets (every attached dataset, in order) and dataset (the first) when any dataset is attached; both fields are 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 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

Datasets stay with the sandbox and everything made from it, in the same order:

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

A snapshot does not include the datasets’ files, so datasets add nothing to your snapshot storage.

Limits and errors

A sandbox can have up to 10 datasets, each mounted read-only at /datasets/<name>. They are chosen at creation and cannot be added to or removed from an existing sandbox. The same dataset cannot be listed twice.
Dataset names use lowercase letters, digits, ., _, and -, start with a letter or digit, and are at most 64 characters.
dataset and datasets 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.
`ValueError` (SDK) or `400`: `at most 10 datasets can be attached to one sandbox`	More than 10 datasets.	Attach at most 10.
`ValueError` (SDK) or `400`: `dataset "<name>" is listed more than once`	The same dataset appears twice in `datasets`.	List each dataset once.
`400`: `datasets "<a>" and "<b>" are the same data; attach only one of them`	Two dataset names hold identical data.	Attach one of them.
`ValueError` (SDK) or `400`: `send either dataset or datasets, not both`	Both fields were sent.	Use `datasets` alone for several.
`InvalidRequestError` / `400`: `attaching more than one dataset is not enabled yet`	Several datasets are not yet enabled on the service.	Attach one dataset, or retry later.
`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.
`ServerError` / `503`: `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.
`ServerError` / `503`: `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.

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

Attach several datasets

Upload your own

Create over HTTP

Read dataset files

Forks, snapshots, and archives

Limits and errors

Usage

​Attach several datasets

​Upload your own

​Create over HTTP

​Read dataset files

​Forks, snapshots, and archives

​Limits and errors

​Usage

Attach several datasets

Upload your own

Create over HTTP

Read dataset files

Forks, snapshots, and archives

Limits and errors

Usage