On Runtime, a Container runs one OCI image from any
registry, under Docker on a Linux machine of its own, and serves the port it
listens on through a preview. It pauses after five minutes with nothing to do,
and the next request resumes it. Name the image in the
RUNTIME_CONTAINER_IMAGE environment variable. Each container is its own
Firecracker microVM, so two containers never share a kernel
(microVM vs container).
Build and push the image
A container host pulls the image from a registry, so the image must be pushed first. With Docker:
Terminaldocker build -t ghcr.io/acme/web:1.4.2 .docker push ghcr.io/acme/web:1.4.2The image needs three things to run well on any host:
| Need | In the Dockerfile |
|---|---|
| A port to route to | The server listens on 0.0.0.0 and a known port. EXPOSE documents it but publishes nothing |
| A command that starts it | CMD or ENTRYPOINT, in the exec form (["node", "server.js"]) so it receives SIGTERM |
| The right CPU type | Build for linux/amd64, or for both with docker buildx build --platform linux/amd64,linux/arm64 |
Tag each build with a version, never only latest. A host that pulls latest
tomorrow may get a different image than you tested. To pin an exact build, use
its digest, ghcr.io/acme/web@sha256:...
(what an OCI image is).
Locally, docker run -p 8080:80 <image> maps a port on your machine to the
port inside the container. A host does the same mapping for you, to an HTTPS
address.
Run it on Runtime
This script runs the public image traefik/whoami, which listens on port 80,
and reads it through a preview. It uses curl and
jq against the API, with your key in
RUNTIME_API_KEY.
Terminalapi=https://api.withruntime.com/v2auth="Authorization: Bearer $RUNTIME_API_KEY"# The image to run, from any registry. traefik/whoami listens on port 80.container=$(curl -sf -X POST "$api/containers" -H "$auth" -H "Content-Type: application/json" \ -d '{"env": {"RUNTIME_CONTAINER_IMAGE": "traefik/whoami"}}' | jq -r .id)trap 'curl -sf -X DELETE "$api/containers/$container" -H "$auth" > /dev/null' EXITpreview=$(curl -sf -X POST "$api/sandboxes/$container/previews" -H "$auth" \ -H "Content-Type: application/json" -d '{"port": 80}')url=$(jq -r .url <<< "$preview")token=$(jq -r .token <<< "$preview")# The first request waits while the image is pulled.curl -sf --retry 60 --retry-all-errors --retry-delay 1 "$url" -H "x-runtime-preview-token: $token" | head -n 1# Hostname: ...The trap deletes the container when the script ends. Leave it out to keep
it. Share the port your own image listens on, which is not always 80. With no
RUNTIME_CONTAINER_IMAGE, a Container runs nginx:stable.
Container or whole machine
A Container runs your image as it is, as one process tree under Docker. To boot the whole machine from your own image instead, with your packages in every sandbox, app or function that starts from it, build a Runtime image from a Dockerfile.
Mistakes to avoid
- Listening on
127.0.0.1. The server answers inside the container and nowhere else. Listen on0.0.0.0. - The shell form of
CMD.CMD node server.jsruns under/bin/sh -c, which does not passSIGTERMon, so a stop waits for its timeout and then kills the process. - An image built only for Arm. An image built on an Apple silicon Mac is
linux/arm64unless you say otherwise. Anamd64host cannot run it without emulation. - Secrets baked into a layer. A key copied in and deleted in a later step is still in the earlier layer. Pass it as an environment variable at run time.
Related
- What is an OCI image?
- What is a container?
- How to deploy a Node.js app, from source without an image
- What is a platform as a service (PaaS)?
Sources
- Docker Docs, Dockerfile reference, checked 17 November 2026
- Docker Docs, docker container run, checked 17 November 2026
Facts on this page were checked on 17 November 2026.