- An image function names any image whose entrypoint reads its input on stdin and writes its output on stdout.
- A source function on an interpreted runtime sends its files, and Alchemy lays them over the Python or Node runtime image.
- A source function on a compiled runtime sends its Go or Rust files, and Alchemy compiles them once before laying the result over the runtime image.
Runtime images
Alchemy publishes one runtime image per language, built fromruntimes/ in the
repository, under ghcr.io/galaxy-io/alchemy/runtime.
go:1.27-build and rust:1.99-build are the matching build images. They hold
the toolchain and the Arrow library with their dependencies already fetched, so
a compile runs offline.
Source builds
A spec withsource carries the files of one handler, not its dependencies,
which come from the runtime image. Nothing is installed at build time.
The server packs the files into a tar under
app/, sorted by path with fixed
timestamps and modes, so the same files always give the same digest. It keeps
the archive in the artifacts bucket (ARTIFACTS_BUCKET) at
<tenant>/layers/<sha256>.tar and leaves the spec naming the archive, with each
file’s path and size but not its content. A server without an artifacts bucket
refuses a source with FAILED_PRECONDITION.
Compiled runtimes
Whenspec.image is the Go or Rust runtime, the server compiles the source
first, once for every host that will run the version:
- It asks the least busy live host to run the build image over the source, in a microVM of its own with 2 vCPUs, 2048 MiB and a 3 minute timeout.
- The build image writes a tar of the compiled files to stdout, and everything else to stderr, which becomes the build log.
- The host keeps the tar in the artifacts bucket at
<tenant>/compiled/<key>.tar, where the key is a digest of the build image’s digest and the source’s. If the tar is already there, the host reuses it and runs no compile. - The version gets the compiled layer in place of its source.
build_log.
Image functions
Any OCI image works.command replaces the image’s Entrypoint and Cmd, and
env is added on top of its Env. A multi-arch image resolves to the host’s
architecture.
Hosts find registry credentials in the Docker config first, then through the
AWS and GCP providers for their own registries, and pull anonymously otherwise.
What a build makes
A build turns a version into an artifact on one host:- The host resolves the image to its digest and flattens it into a read-only ext4 root filesystem with the supervisor inside. It is cached by image digest and shared by every version on that image.
- When the version has layers, the host extracts them into a second read-only ext4 drive, cached by the layers’ digests. The guest overlays it on the root filesystem at boot.
- The host boots the microVM once and snapshots it. See Isolation.
READY once that host is done. Every other host builds
the artifact itself the first time it takes one of the version’s invocations,
from the image pinned to its digest, so a tag that moved since never changes
what runs. Invocations that arrive during that build wait for it.
The artifact’s id hashes the version and everything that went into it: the
image digest, the command, env, the layers, the resources and the secret names.
A change of the function’s resources is a new artifact.
Hosts keep the newest 2 versions of each function built (KEPT_VERSIONS). An
older version that goes 24 hours without an invocation (VERSION_IDLE_TTL) is
dropped with its snapshot and drives, and the next invocation builds it again.
How runtime images are published
.github/workflows/runtimes.yaml runs on every push to main that touches
runtimes/. For each runtime it computes a tag of the version and the git tree
hash of the runtime’s directory, such as 3.13-<treehash>.
- When that tag is already published, the runtime has not changed and nothing is built.
- Otherwise the image is built and pushed as both
<version>and<version>-<treehash>, with a build provenance attestation.
force rebuilds every runtime. A function that needs a
runtime to stay fixed can name the <version>-<treehash> tag, while
<version> follows the latest build. Either way a version runs the digest it
resolved at build time.