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 avoids storing any long-lived secret. Register the registry host with kind="ecr-assume-role", an IAM role_arn in your AWS account, and an external_id you choose:

box.registries.put(
    host="123456789012.dkr.ecr.us-east-1.amazonaws.com",
    kind="ecr-assume-role",
    role_arn="arn:aws:iam::123456789012:role/lithosbox-ecr-pull",
    external_id=os.environ["LITHOSBOX_ECR_EXTERNAL_ID"],
)

At pull time, LithosBox assumes that role via AWS STS using your external ID and mints a short-lived ECR authorization token, which is cached briefly and never stored. Your role needs two things: permissions to read the images (ecr:GetAuthorizationToken, plus ecr:BatchGetImage and layer-download actions on the repositories you use), and a trust policy that allows the LithosBox platform’s AWS account — provided during onboarding — to assume the role, conditioned on your external_id. Request and response fields are in 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 yet supported. Each sandbox has a writable disk (16 GiB by default; 32 GiB with writable_size_bytes, and 64 GiB on upgraded plans). The disk size is part of an image’s prepared configuration, like CPU and memory: the first create of an image at a non-default size prepares that configuration once, as described in Wait for an image. 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, or allow_egress=[...] to allow only listed hosts (see Limit outbound network 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

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