- From source. You send
main.go. A host compiles it in a microVM on thego:1.27-buildimage and the version runs the binary ongo:1.27. - As an image. You compile the binary yourself and copy it into an image
on
static:13.
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:
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
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 namesgo: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:
- The least busy host boots
go:1.27-buildin a microVM of its own, with 2 vCPUs and 2 GiB, or the host’s whole memory budget when that is smaller. - The build image copies your files into the module and runs
go build -ldflags='-s -w'. The compiler’s output is the build log. - The host stores the binary as a layer in the artifacts bucket, and the
version is built from
go:1.27with that layer at/app/handler.
GetFunctionVersion returns.
1
Create the function
.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
statusMessage starts with
compile failed: and buildLog holds the compiler’s output.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 ontostatic:13:
Dockerfile
static:13 has no libc, so build with CGO_ENABLED=0. Build for the hosts’
architecture and push:
source:
Invoke it
POST the input with the contract’s content type. For the Arrow example, writeinput.arrows as in the Python guide:
-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.