> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanovm.dev.lithosai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Use custom images

> Choose a sandbox image, use a private registry, and prepare reusable templates.

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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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](/reference/http-api#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:

```python theme={null}
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](/guides/run-commands#keep-shell-state),
or included in the image; `create()` does not accept an environment-variable map.

When finished with the final example:

```python theme={null}
sandbox.delete()
box.close()
```