Skip to main content
This guide takes a Python handler from a file on your machine to a deployed, invoked function. It covers both contract kinds and both ways to deploy: source files that Alchemy lays over the runtime image, and an OCI image you build yourself. 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 Python runtime

Nothing is installed at build time. A function built from source can import the standard library, pyarrow and its own files under /app. A function that needs other packages ships as an image. The image prefix is the server’s RUNTIME_IMAGE_PREFIX (runtimes.imagePrefix in the Helm chart). ListRuntimes returns the exact image for your server, so ask it rather than typing the reference:

The protocol

Every Alchemy function speaks the same protocol. For each invocation the supervisor in the microVM starts the entrypoint as a new process and:
  • writes the input to stdin, then closes it
  • takes everything the process writes to stdout as the output
  • streams stderr to the invocation’s log
  • treats a non-zero exit as a crash, with the exit status and the last 4 KiB of stderr as the error message
The input and output encoding comes from the contract. A JSON Schema contract passes one JSON value each way. An Arrow contract passes one Arrow IPC stream holding exactly one record batch each way. The platform checks the input before the function runs and the output before the caller sees it. See Contracts. Because each invocation starts a new process, keep module level work small. Interpreter start and imports are paid on every call.

Write a JSON handler

This is the runtime’s JSON Schema starter, which the web UI also offers. It reads one value, returns it unchanged and lets any exception exit non-zero:
handler.py
Replace handler with your logic. Print diagnostics with print(..., file=sys.stderr). Anything printed to stdout becomes part of the output and will likely break the contract.

Write an Arrow handler

An Arrow function receives a batch of rows and returns a batch with the same number of rows in the same order. The platform rejects an output whose row count differs from the input’s. examples/embed/python/handler.py is a complete one. It reads a batch with an id and a text column and returns, per row, the cleaned text, its token count and a 64-dimension embedding. Its shape is the runtime’s Arrow starter:
handler.py
An Arrow contract carries both schemas as serialized Arrow IPC schema messages. Write them for the embed example with pyarrow:
schemas.py
Fields are matched by position, name, type and nullability. A column the contract marks nullable accepts a non-nullable one, not the other way round. The web UI builds the same schemas from its field editor.

Deploy from source

A function built from source has no image of its own. Its spec names the runtime image and carries the files. The server stores them as an archive in its artifacts bucket and hosts extract it over the image at /app. The files are limited to 64 per version and 1 MiB in total, and the runtime runs handler.py.
Source builds need the server’s ARTIFACTS_BUCKET and the hosts’ access to it. Without one, CreateFunction answers failed_precondition: the server has no artifacts bucket, so functions are built from images only.
1

Create the function

protocol is required and INVOCATION_PROTOCOL_EXEC is the only one implemented. timeoutMs, maxConcurrency, retries and resources are optional on the request: zero takes the server defaults of a 30 s timeout, no concurrency limit, 1 vCPU and 128 MiB, and an unset retries takes 2.
2

Wait for the build

The first version starts in BUILDING. A host pulls the runtime, lays the files over it, boots the microVM and snapshots it. Only a READY version can be invoked.
A FAILED version carries the reason in statusMessage and the tail of the build output in buildLog.
To change the code, send a new spec with CreateFunctionVersion, or click New version on the function. The new version becomes current once it is READY, and the previous one keeps serving until then.

Deploy as an image

Ship an image when the function needs packages the runtime does not have. Build on the runtime so the entrypoint stays python /app/handler.py. The embed example’s Dockerfile is two lines:
Dockerfile
Add a RUN pip install ... line for extra packages. Build for the hosts’ architecture and push to a registry the hosts can pull from:
Then create the function with that image and no source:
In the web UI, choose Image instead of Code and enter the reference. The version resolves the tag to a digest when it builds and always runs that digest, so pushing the tag again changes nothing until you create a new version. See Deploy any OCI image for private registries.
With the local setup, push to localhost:5001 and reference the image as 192.168.5.2:5001/... in the spec. That is the address the hosts in the Lima VM reach the compose registry by.

Invoke it

POST the input to /functions/<function-id>/invoke with the contract’s content type. The response body is the output.
The response names the invocation in Alchemy-Invocation-Id and the version that ran in Alchemy-Version. A function that exits non-zero answers 500 with its error as JSON, and one that runs past its timeout answers 504. Open the function’s Invocations tab to read the call’s stderr, or use the Workbench tab to invoke it from the browser. The same call is FunctionsService.Invoke on the API, with the input as bytes. See HTTP invoke for pinning versions, retries, idempotency keys and async calls.

Next steps

Troubleshooting

Read contract violations, crashes, timeouts and build failures.

Runtimes and builds

How a spec becomes a root filesystem and a snapshot.

Secrets

Give a function credentials without putting them in its spec.

Invocations

Queueing, retries, start kinds and the invocation lifecycle.