Sandbox 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:

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:

TypeScript
Python
REST

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 });

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)

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:

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:

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 for running. If it becomes failed, inspect exit_reason.

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 and 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.

Getting started

Compute

Concepts

Data Sources

Details

Administration

Protocols

Reference

Legal

Sandbox images

Public images

Private images

Reusing and updating images

​Public images

​Private images

​Reusing and updating images

Public images

Private images

Reusing and updating images