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

# Sandbox images

> Start sandboxes from public or private OCI images and reuse prepared images.

Choose an OCI image with the tools and dependencies your workload needs. Archil supports public and private Linux
images built for `amd64`.

## Public images

For a public image, pass `baseImage` in TypeScript, or `base_image` in Python and REST, when creating a sandbox:

```typescript theme={null}
const sandbox = await client.sandboxes.create({ baseImage: "python:3.13" });
```

You can use Docker Hub shorthand, as above, or a full reference such as `ghcr.io/acme/agent-runtime:v2`.
If you omit the image, the sandbox starts from `ubuntu:26.04`.

## Private images

For a private image, build it with your registry credentials first. The SDK waits until the image is ready,
then you can pass its ID when creating a sandbox:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Archil } from "disk";

    const client = new Archil({
      apiKey: process.env.ARCHIL_API_KEY,
      region: "aws-us-east-1",
    });
    const image = await client.images.build({
      source: "ghcr.io/acme/agent-runtime:v2",
      registryAuth: {
        username: process.env.REGISTRY_USERNAME!,
        password: process.env.REGISTRY_TOKEN!,
      },
    });

    const sandbox = await client.sandboxes.create({ imageId: image.imageId });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from archil import Archil, RegistryAuth

    with Archil(region="aws-us-east-1") as client:
        image = client.images.build(
            source="ghcr.io/acme/agent-runtime:v2",
            registry_auth=RegistryAuth(
                username=os.environ["REGISTRY_USERNAME"],
                password=os.environ["REGISTRY_TOKEN"],
            ),
        )
        sandbox = client.sandboxes.create(image_id=image.image_id)
    ```
  </Tab>

  <Tab title="REST">
    ```bash theme={null}
    curl --request POST \
      'https://control.green.us-east-1.aws.prod.archil.com/api/images' \
      --header "Authorization: $ARCHIL_API_KEY" \
      --header 'Content-Type: application/json' \
      --data '{
        "source": "ghcr.io/acme/agent-runtime:v2",
        "registry_auth": {
          "username": "YOUR_REGISTRY_USERNAME",
          "password": "YOUR_REGISTRY_TOKEN"
        }
      }'
    ```

    The response contains `data.image_id`. Set `IMAGE_ID` to that value and poll until `data.status` is `ready` or `failed`:

    ```bash theme={null}
    curl "https://control.green.us-east-1.aws.prod.archil.com/api/images/$IMAGE_ID" \
      --header "Authorization: $ARCHIL_API_KEY"
    ```

    If the build fails, inspect `failure_reason`. Once it is `ready`, create the sandbox:

    ```bash theme={null}
    curl --request POST \
      'https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes?wait=true' \
      --header "Authorization: $ARCHIL_API_KEY" \
      --header 'Content-Type: application/json' \
      --data "{\"image_id\": \"$IMAGE_ID\"}"
    ```

    If the sandbox response is still `pending`, poll [Get Sandbox](/api-reference/sandboxes/get-sandbox) for `running`.
    If it becomes `failed`, inspect `exit_reason`.
  </Tab>
</Tabs>

Use a registry username and a password or token with pull access. Archil does not store these credentials, so supply
them each time you build. Once built, the image is available to sandboxes in your account without registry credentials.

See [Build Image](/api-reference/images/build-image) and [Get Image](/api-reference/images/get-image) for request
options and build failures.

## Reusing and updating images

Archil prepares each image for use as a sandbox filesystem. To finish this work before creating sandboxes, build
once and reuse the returned image ID. You can also prebuild public images by omitting the registry credentials.

If you publish a new version under the same tag, build it again to pick up the change. New sandboxes using that
image ID get the latest successful build. While a rebuild is in progress, they can still use the previous successful
build. Existing sandboxes keep their original image, including after a restart.

To pin an image to a specific version, use a digest reference such as `repository@sha256:...` instead of a tag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.