Images

A sandbox boots an OCI image for linux/amd64. Archil pulls the image once, records the digest it resolved, and every sandbox booted from it starts from that digest. Archil has no builder: it pulls images, so an image from a Dockerfile is built on your machine and pushed to a registry first.

Alchemy builds the Dockerfile with your Docker and pushes it to your registry. Archil pulls it from there and boots sandboxes from the digest it pulled.

Use a public image directly

A public image needs no resource. Name it as a sandbox’s baseImage:

src/devbox.ts

export const DevBox = Archil.Sandbox("DevBox", { baseImage: "python:3.13" });

A sandbox with neither baseImage nor image boots node:24-bookworm.

Pin an image

Archil.Image pulls an image once and keeps its digest, so every sandbox boots the same bits even after the tag moves:

src/images.ts

export const Base = Archil.Image("Base", { image: "node:24-bookworm" });

Pass its imageId to a sandbox:

src/devbox.ts

export const DevBox = Effect.gen(function* () {
  const base = yield* Base;
  return yield* Archil.Sandbox("DevBox", { image: base.imageId });
});

Changing image pulls it again.

Pull from a private registry

Give the registry’s credentials. Archil uses them to pull this image and doesn’t store them:

src/images.ts

export const Agent = Archil.Image("Agent", {
  image: "ghcr.io/acme/agent:1",
  registry: {
    server: "ghcr.io",
    username: "acme-bot",
    password: Config.Redacted("GHCR_TOKEN"),
  },
});

Build a Dockerfile

Give a dockerfile and where to push it. Alchemy builds it with your local Docker, pushes it tagged with the build’s hash, and Archil pulls it:

src/images.ts

export const Agent = Archil.Image("Agent", {
  dockerfile: "./agent/Dockerfile",
  context: "./agent",
  push: {
    repository: "ghcr.io/acme/agent",
    credentials: { server: "ghcr.io", username: "acme-bot", password: Config.Redacted("GHCR_TOKEN") },
  },
});

The credentials need to push to the repository and pull from it. A change to the Dockerfile or its context builds and pushes a new tag.

Build images while the app runs

Archil.CreateImage pulls images at run time, e.g. one per customer repository, with the same props as Archil.Image:

const images = yield* Archil.CreateImage();
const image = yield* images.build({ image: `ghcr.io/acme/${tenant}:latest` });
const sandbox = yield* sandboxes.create({ name: tenant, image: image.imageId });

Programs that need a filesystem client

A program sandbox boots a public image. When one of its bindings installs a filesystem client, like a mount for another storage service, Alchemy builds an image of the base plus that client the same way, so give the sandbox a push too.

Deleting

Archil has no API to delete an image. Destroying an Archil.Image removes it from Alchemy’s state only, and the image pushed to your registry stays there.