Choosing a runtime

Archil runs code next to a disk in four ways. Three of them are Firecracker microVMs that Archil runs, and the fourth is a host you already run, with the disk mounted. They differ in how long the code lives and who keeps it running.

execper call

programsandbox + main

sandboxper task

mountyour host

your code

you

processes

Archil

you

machine lifetime

Archil

you

image

Archil

you

host & client

Archil

you

From left to right, Archil manages less and you decide more. A mount runs on a host you already run, so everything under your code is yours.

Serverless exec: one call, one microVM

Archil.ExecDisk runs one command against a disk. Each call boots a microVM with the disk at /mnt/archil, runs the command to completion, and shuts down. Many calls run at once, and each one is a single charge.

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

A call runs for at most five minutes and keeps nothing but what it writes to the disk. Choose it for an agent’s shell tool, a search, or a batch over a dataset. See Disks.

commandboot

Each call gets its own microVM with the disk mounted, and it's gone when the command exits.

Program sandboxes: your program at a URL

An Archil.Sandbox with a main runs your program. Archil’s service manager keeps it running, and its port gets a public https:// URL. The sandbox pauses when idle, and the next request wakes it.

import * as Archil from "@alchemy.run/archil";
import * as Effect from "effect/Effect";
import * as HttpServerResponse from "effect/http/HttpServerResponse";

export default class Api extends Archil.Sandbox<Api>()(
  "Api",
  { main: import.meta.url },
  Effect.gen(function* () {
    return { fetch: Effect.succeed(HttpServerResponse.text("hello")) };
  }),
) {}

Choose it for APIs and websites that live next to their data. See Programs.

paused, not billedwake

One sandbox serves every request. It pauses once idle, and a request to its URL wakes it with its memory intact.

Sandboxes created at run time: one per task

Archil.CreateSandbox gives a Worker or Lambda a client that creates sandboxes by name, from an image. Your code drives each one: it runs commands, starts processes, opens terminals and deletes it when the task is done.

const sandboxes = yield* Archil.CreateSandbox(Agent);
const sandbox = yield* sandboxes.create({ name: `task-${id}` });
yield* sandbox.exec("npm test");

Choose it for agent loops and preview environments, where each user or task needs a machine of its own. See Sandboxes.

Each task gets its own sandbox. It keeps its files and memory while paused, until your code deletes it.

Mounts: a disk on your own host

Archil.MountDisk on a Cloudflare Container or an ECS task on EC2 installs Archil’s FUSE client in the host’s image. The host mounts the disk while it handles a request, with a mount token for that disk only.

const dataset = yield* Archil.MountDisk(Dataset, { path: "/data", mode: "read-only" });
const path = yield* dataset.mount();

Choose it when the code already runs somewhere else and needs the files. See Mounting.

Indexeryour Containermount token: Dataset

your programEffect

archil clientFUSE

mount: /data
mode: read-only

The host runs your program and the Archil client side by side. Its token mounts one disk.

Mix runtimes in one app

One disk serves all of them at once. A program serves the files, a Worker runs commands against them, and your Container reads them to build an index:

Three runtimes on one disk at once. An exclusive mount locks the disk for one writer, so mount it read-only or conditional where several clients share it.