Use custom images

Pass an OCI image reference to start a sandbox with the software you need:

from lithosbox import LithosBox

box = LithosBox()
sandbox = box.sandboxes.create(
    image="python:3.12-slim",
    cpus=2,
    memory_mb=2048,
)
print(sandbox.run(["python3", "--version"]).check().stdout)
sandbox.delete()

Omit image to use the default environment, which includes Python 3.12 and Node.js 22 with 2 vCPU and 1 GiB of memory. For reproducible environments, use a specific image version or digest and include frequently used dependencies in your image.

Wait for an image

The first use of an image and configuration may require preparation. The SDK waits by default. Large images can take several minutes; increasing warm_timeout gives the SDK more time to wait:

sandbox = box.sandboxes.create(
    image="python:3.12-slim",
    warm_timeout=1800,
)
sandbox.delete()

The default image-preparation wait is 900 seconds. This is separate from the five-minute timeout for a create request. Avoid wrapping create() in a shorter timeout when preparing a new image. If a wait expires, preparation may still be in progress. Check the template’s status and status_detail, or continue waiting with box.templates.wait(). If the create request itself loses its connection, check box.sandboxes.list() before creating another sandbox.

Prepare a reusable template

Create a named template and wait until it is ready:

template = box.templates.create(
    name="python-workspace",
    image="python:3.12-slim",
    cpus=2,
    memory_mb=2048,
)
template = box.templates.wait(template.id)
sandbox = box.sandboxes.create(template=template.id)
print(sandbox.run(["python3", "--version"]).check().stdout)
sandbox.delete()

Create from that template ID or name in later runs. It uses the template’s CPU, memory, runtime, and network configuration. Prepare another template when you need a different configuration. box.templates.list() shows available templates. Shared templates are marked shared=True and are read-only. Use box.templates.delete(template.id) to remove a template you own when you no longer need it.

Use a private registry

Store registry credentials for your organization before creating from a private image. Read secrets from your environment rather than putting them in code:

import os

box.registries.put(
    host="ghcr.io",
    username=os.environ["REGISTRY_USERNAME"],
    password=os.environ["REGISTRY_TOKEN"],
)
sandbox = box.sandboxes.create(image="ghcr.io/YOUR_ORGANIZATION/YOUR_IMAGE:TAG")
sandbox.delete()

box.registries.list() lists configured registries without returning their secrets. Use box.registries.delete("ghcr.io") to remove a stored credential. For AWS ECR role-based access, see Registries.

Choose a runtime

The default runtime="container" runs the image’s application. Use runtime="vm" for workloads that need Docker or services such as systemd inside the sandbox:

sandbox = box.sandboxes.create(image="docker:28-dind", runtime="vm")

With a Docker-in-Docker image, use its existing Docker daemon rather than starting a second one. Allow the daemon to become ready before issuing Docker commands.

Image requirements and networking

Use compatible Linux images. GPU workloads are not supported. Each sandbox has a fixed 16 GiB writable disk, separate from the CPU and memory settings. Outbound connections use IPv4. Give package downloads a finite timeout and retry transient failures. For example, apt-get -o Acquire::Retries=3 update retries failed package-index downloads. Preinstall large dependencies in your image when possible so each task does not need to download them again. Set disable_internet=True at creation to disable outbound internet access. That setting also applies to snapshots restored from the sandbox and to its forks. Environment variables are set through a command or session, or included in the image; create() does not accept an environment-variable map. When finished with the final example:

sandbox.delete()
box.close()

Getting Started

Reference

Guides

Concepts

Wait for an image

Prepare a reusable template

Use a private registry

Choose a runtime

Image requirements and networking

​Wait for an image

​Prepare a reusable template

​Use a private registry

​Choose a runtime

​Image requirements and networking

Wait for an image

Prepare a reusable template

Use a private registry

Choose a runtime

Image requirements and networking