Skip to main content
This guide runs the whole stack on your machine: PostgreSQL, NATS, an object store and a registry in Docker, KVM hosts in a Lima VM, and the server and web UI on the Mac. Then it creates a Python function and invokes it.

Requirements

Firecracker needs /dev/kvm, which Docker Desktop does not provide. The justfile runs the hosts in a Lima VM with nested virtualization, which needs:
  • An Apple silicon Mac with an M3 chip or later
  • macOS 15 or later
The local setup is built for macOS. The vm and host recipes drive Lima and run the linux-arm64 host build inside it, and there is no recipe for running hosts directly on a Linux machine with /dev/kvm. You also need:
  • Docker, used through its default context
  • Node.js 22 or later with pnpm, for the UI
  • The rest of the toolchain from the repository’s Brewfile: Go, just, buf, golangci-lint, jq, the RustFS rc client and Lima

Run it

1

Start local infrastructure

Starts PostgreSQL, NATS with JetStream, RustFS and a registry through Compose, then makes the alchemy-logs and alchemy-artifacts buckets.
Each port can be moved with its ALCHEMY_*_PORT variable in docker-compose.yaml.
2

Start the KVM host VM

Creates the alchemy Lima VM on first run from lima.yaml, with 4 CPUs, 8 GiB of memory, Firecracker, its jailer and a guest kernel. Later runs start the existing VM.
3

Build the images

Builds the server and host images, then builds every runtime (Python, Node, static, Go and Rust) and pushes them to the local registry, where the hosts pull them.
4

Run Alchemy

Starts 3 hosts in the VM with 512 MiB each, starts the server on :8780, waits for its /healthz, then starts the UI dev server. The server applies database migrations when it starts. Ctrl-C stops everything.
Open http://localhost:5173. The UI dev server proxies the API to the server on :8780.
just server falls back to a fixed ENCRYPTION_KEY so the secrets API works out of the box. It is a published development key. Never use it outside local development.

Create a function

A function built from source is a handler laid over a runtime image at /app. The Python runtime runs /app/handler.py, which reads one JSON value on stdin and writes one on stdout.
1

Write the handler

Save this as handler.py:
handler.py
2

Create the function

The function’s first version starts in BUILDING. A host pulls the runtime, lays the handler over it, boots it and snapshots the microVM. The version turns READY when that finishes, and only a ready version can be invoked.
3

Wait for the build

Watch the version on the function’s Versions tab, or ask the API:

Invoke it

POST the input to the function’s invoke endpoint with the content type its contract takes. The response body is the output.
An input that breaks the contract is rejected before any microVM is used. Try -d '{}' to see the violation. See HTTP invoke for versions, retries, idempotency keys and async calls.

See it in the UI

Open the function and select Invocations to see the call with its status, attempts and duration, and open it to read its log. The Workbench tab invokes the function from the browser. Invocations in the sidebar lists calls across every function.

Stop everything

Ctrl-C stops just dev. Then stop the VM and the infrastructure:
just infra down volumes also drops the data, and just vm delete removes the VM.

Next steps