Skip to main content
A Rust function is a static binary that reads its input on stdin and writes its output on stdout. Alchemy runs it two ways:
  • From source. You send main.rs. A host compiles it in a microVM on the rust:1.99-build image and the version runs the binary on rust:1.99.
  • As an image. You compile the binary yourself and copy it into an image on static:13.
The commands assume a server on localhost:8780 with no auth, as in the Quickstart. With auth enabled, add -H "Authorization: Bearer $TOKEN" to every call.

The Rust runtime

The default prefix is ghcr.io/galaxy-io/alchemy/runtime, set by the server’s RUNTIME_IMAGE_PREFIX. Ask the server for the exact image:
Compiles run offline with cargo build --release --offline. Your files land in a crate named handler, edition 2024, whose binary is built from main.rs. Its dependencies are fixed: A function that needs other crates ships as an image.

The protocol

For each invocation the supervisor starts /app/handler as a new process, writes the input to stdin and closes it, takes stdout as the output and streams stderr to the invocation’s log. A non-zero exit, including a panic, is a crash, reported with the exit status and the last 4 KiB of stderr. A JSON Schema contract passes one JSON value each way, an Arrow contract one IPC stream with exactly one record batch. See Contracts.

Write a handler

The runtime’s JSON Schema starter:
main.rs
The Arrow starter has the same shape around RecordBatch:
main.rs
The output batch must have as many rows as the input, in the same order. examples/embed/rust is a complete Arrow function that returns the cleaned text, its token count and a 64-dimension embedding per row. It is a standalone crate on arrow 57, built as an image below. The Arrow contract’s schemas are serialized Arrow IPC. Build them as in the Python guide, which writes arrow.json for the embed example, or define the fields in the web UI.

Deploy from source

A source version names rust:1.99 as its image and carries main.rs. When the version builds, the server compiles it first:
  1. The least busy host boots rust:1.99-build in a microVM of its own, with 2 vCPUs and 2 GiB, or the host’s whole memory budget when that is smaller.
  2. The build image copies your files into the crate and runs cargo build --release --offline. The compiler’s output is the build log.
  3. The host stores the binary as a layer in the artifacts bucket, and the version is built from rust:1.99 with that layer at /app/handler.
A compile has 3 minutes. Its result is kept by the build image’s digest and the source’s, so the same files on the same build image compile once. A republished build image compiles afresh.
1

Create the function

Modules declared with mod in main.rs can be sent as more .rs files next to it. Do not send a Cargo.toml or Cargo.lock: they replace the crate’s, and a dependency the build image has not compiled fails the offline build.
2

Wait for the build

A compile error fails the version. statusMessage starts with compile failed: and buildLog holds cargo’s output.
Only the exact image ListRuntimes returns is compiled. A source on any other reference to the Rust runtime is laid over the image uncompiled, and every invocation crashes because /app/handler does not exist.

Deploy as an image

Build the binary yourself for other crates or build settings. The embed example builds against musl and copies the binary onto static:13:
Dockerfile
static:13 has no libc, so the binary must be fully static, which the Alpine (musl) toolchain gives by default. Build for the hosts’ architecture and push:
Create the function with that image and no source:
See Deploy any OCI image for private registries.

Invoke it

POST the input with the contract’s content type:
Write input.arrows as in the Python guide. The response carries Alchemy-Invocation-Id and Alchemy-Version. A handler that panics or exits non-zero answers 500, and one past its timeout 504. See HTTP invoke.

Next steps

Troubleshooting

Read compile failures, crashes and contract violations.

Runtimes and builds

How a spec becomes a root filesystem and a snapshot.