Rules: images and changes

Last updated 2 November 2026

Check these rules when you build an image or change a Machine: each keeps it starting, and running the version you meant.

The examples use the database a Machine opens as Keep data in its database shows, and a node:http server.

Name the smallest shape that fits

With no shape named, the CLI gives a Machine m-8, 8 vCPUs and 16 GiB at up to $0.6888 an awake hour, and every wake reserves ten minutes of it (see Each shape’s most).

tonbo machine create app --image registry.example.com/you/app:1 --shape s-1 --port 8080

tonbo machine create app --image registry.example.com/you/app:1 --port 8080 # m-8, 8 vCPUs

Build the image for linux/arm64

Machines run only linux/arm64 images, and a create that names another is refused (see Build for linux/arm64).

docker buildx build --platform linux/arm64 -t registry.example.com/you/app:1 --push .

docker build -t registry.example.com/you/app:1 . && docker push registry.example.com/you/app:1 # your computer's platform

Use a glibc-based image when the Machine opens its database

The database package is built for Linux arm64 with glibc 2.28 or later, not for musl (see Requirements).

FROM node:22-bookworm-slim

FROM node:22-alpine

Name the tag again after you push to it

A tag is resolved to its digest when you name it, so a push under the same tag changes nothing until an update names it again (see A new image under the same tag).

docker push registry.example.com/you/app:1
tonbo machine update app --image registry.example.com/you/app:1

docker push registry.example.com/you/app:1 # the Machine keeps the digest it resolved

Put the Machine to sleep to apply a change now

An image, command, env or shape change applies at the next wake, and a Machine that is called often may not sleep for a long time (see Apply it now).

tonbo machine update app --image registry.example.com/you/app:2
tonbo machine sleep app

tonbo machine update app --image registry.example.com/you/app:2 # the old version runs while requests keep it awake