What is Archil?

Archil runs code against your data. Your files live on disks, POSIX filesystems backed by object storage. Archil runs code against a disk in a Firecracker microVM, either one call at a time (serverless exec) or in a sandbox that stays around. Any other Linux machine can mount the disk too. Every disk, sandbox and image belongs to an organization and lives in one region.

Take one small app: a Dataset disk of CSV files. A Cloudflare Worker counts their rows with a serverless call. An Api sandbox serves them at a public URL. A Container you run elsewhere mounts the disk to index it. The disk keeps recent data on Archil’s fast storage and the rest in its bucket.

The disk, the sandbox and each exec call live in one region of your organization. Each exec call and the sandbox mount the disk, and the Indexer mounts it over the network from outside. The Worker starts exec calls through Archil's API.

Organizations and API keys

A personal account or an organization owns your disks, sandboxes and images, and the bill for them. An organization lets a team share disks: its members can manage them, and its administrators manage the members.

Archil’s control plane takes an API key, created in the console. A key works for one account or organization in one region, and can call every operation there. Archil can’t create narrower keys, so Alchemy deploys with yours.

alchemy profile edit --add Archil

See Organization and keys.

Regions

A region is where a disk’s data and the microVMs that use it run: aws-us-east-1, aws-us-west-2, aws-eu-west-1 or gcp-us-central1. Serverless exec and sandboxes run only in the AWS regions, so keep a disk you run code against in one of them.

Your profile sets the region for everything the Stack deploys.

Disks

A disk is a filesystem that behaves like a local one (POSIX, git, SQLite), stored in object storage. The data a client is using sits in Archil’s storage layer in front of the bucket, so reads and writes are fast, and the bucket holds everything. The bucket is Archil’s unless you bring your own.

src/storage.ts

export const Dataset = Archil.Disk("Dataset", {});

The same disk is also an S3-style bucket, so a host can read and write its files by key without mounting it.

See Disks.

Serverless exec

Serverless exec runs one command against a disk: Archil boots a microVM with the disk at /mnt/archil, runs the command to completion (up to five minutes), and shuts it down. Each call is one charge, and a disk takes many calls at once. Files the command writes stay on the disk.

const dataset = yield* Archil.ExecDisk(Dataset);
const result = yield* dataset.exec("wc -l /mnt/archil/*.csv");

That makes it the natural place for an agent’s shell tool, or a search across a large dataset.

See Choosing a runtime.

Sandboxes

A sandbox is a microVM that stays around between calls. Its root filesystem is a disk of its own, it can mount other disks, and its ports can be public. It pauses when idle, keeping its memory and processes, and resumes on the next connection. A fork copies it, memory and all.

src/devbox.ts

export const DevBox = Archil.Sandbox("DevBox", {
  mounts: [{ disk: Workspace, path: "/workspace" }],
  ports: [3000],
});

Give a sandbox a main, and it runs your program at a public https:// URL.

See Sandboxes and Programs.

Images

A sandbox boots an image: any public OCI image, or one Archil pulls from your private registry. Archil doesn’t build images, so a Dockerfile is built on your machine and pushed to a registry first.

See Images.

Mounts and mount modes

A mount puts a disk at a path, in a sandbox or on any Linux machine running Archil’s FUSE client. Its mode decides who can write: exclusive (the default) gives one client the whole disk, conditional lets many write anywhere, shared lets many write the paths they check out, and read-only never writes.

See Mounting.

Disk users and tokens

A disk user is access to one disk: a mount token, an S3 key pair, or an AWS role that mounts with its own identity. Archil checks it itself, so a host holding one can’t reach any other disk. Alchemy creates one per host for the bindings that need them.

See Credentials and bindings.

Checkpoints and branches

A checkpoint is a named snapshot of a disk, and a branch is a writable copy started from one. Both take tens of milliseconds whatever the disk’s size, and writes on a branch never reach its source.

See Branches and checkpoints.

Egress policy

Every sandbox has an egress policy that Archil enforces outside the microVM. It can deny everything but a list of hosts, and add headers, like an API key, to requests on their way out, so code inside never sees the value.

See Network.

State: where Alchemy keeps its record

Archil has no storage for Alchemy’s own record of what each Stack created. Keep it on disk with Alchemy.localState(), or share it with your team and CI through Cloudflare.state() or AWS.state().

How @alchemy.run/archil models these concepts

Your profile picks the API key and the region, and Archil.providers() deploys into them. The few long-lived things an app shares (a dataset disk, a seeded checkpoint, an image, a dev box, a program) are resources in the Stack. Disks, sandboxes, branches and images made per user or task come from run-time bindings (CreateDisk, CreateSandbox, BranchDisk, CreateImage). Archil has no tags, so the disks and sandboxes they create carry their stack, stage and binding in a name prefix, and stay when the Stack is destroyed. Bindings that touch one disk give their host its own disk user, never your key.

Next, build one: the tutorial puts these ideas to work, one step at a time.