Skip to main content
A Go 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.go. A host compiles it in a microVM on the go:1.27-build image and the version runs the binary on go:1.27.
  • 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 Go 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. Your files land in a module named handler whose only requirement is github.com/apache/arrow-go/v18 v18.8.0, so a source can import the standard library and Arrow, nothing else. A function with other dependencies 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 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.go
For an Arrow contract, read with ipc.NewReader(os.Stdin), take one record batch, and write one batch with the same number of rows through ipc.NewWriter(os.Stdout, ...). examples/embed/go/main.go is a complete one. It reads id and text columns and returns the cleaned text, its token count and a 64-dimension embedding per row. It uses the same Arrow version as the runtime, so it compiles as a source unchanged. 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 go:1.27 as its image and carries main.go. When the version builds, the server sees that the image has a build image and compiles first:
  1. The least busy host boots go:1.27-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 module and runs go build -ldflags='-s -w'. 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 go:1.27 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. The version’s spec keeps your source, which GetFunctionVersion returns.
1

Create the function

Send .go files only. A go.mod or go.sum you send replaces the module’s, and any requirement the build image has not downloaded fails the offline build.
2

Wait for the build

A compile error fails the version. statusMessage starts with compile failed: and buildLog holds the compiler’s output.
Only the exact image ListRuntimes returns is compiled. A source on any other reference to a Go runtime, such as the public ghcr.io image on a server whose prefix points elsewhere, is laid over the image uncompiled, and every invocation crashes because /app/handler does not exist.

Deploy as an image

Build the binary yourself when it needs other modules or build flags. The embed example compiles in one stage and copies the binary onto static:13:
Dockerfile
static:13 has no libc, so build with CGO_ENABLED=0. 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. For the Arrow example, write input.arrows as in the Python guide:
For a JSON contract, send -H 'Content-Type: application/json' and the value with -d. The response carries Alchemy-Invocation-Id and Alchemy-Version. A handler that 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.