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
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
defaultcontext - 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 RustFSrcclient 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 Open http://localhost:5173. The UI dev server
proxies the API to 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.: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
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.-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 stopsjust 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
- Write a Python function covers handlers, Arrow contracts and logs in more depth.
- Architecture follows an invocation from the server through a host to the microVM.
- Local development lists every recipe and how each piece runs in development.