> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Run your own image

Last updated 2 November 2026

> Machines are not open yet. These pages describe Machines as they will open; until then, a create answers [`region_not_offered`](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered) (422), “Machines are not offered in any region yet.”

Package your own program for a Machine when the quickstart’s image is not enough: how to build and publish its image, how the Machine runs it, and what it finds inside.

## Build for linux/arm64

A Machine runs only `linux/arm64` images, from a registry that serves them without credentials. Build and push one with Docker’s [multi-platform builds](https://docs.docker.com/build/building/multi-platform/), which work from an x86 computer too:

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

A program that opens its database starts from a glibc-based image, such as:

**Dockerfile**

```text
FROM node:22-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json server.js ./
RUN npm ci --omit=dev
CMD ["node", "server.js"]
```

## Try it on your computer first

What a Machine’s program prints cannot be read, so run the image on your computer before you create the Machine, to check that it starts. The variables the platform sets (below) exist only on a Machine, so on your computer a program that opens its database stops at the open:

```shell
docker run --platform linux/arm64 -p 8080:8080 registry.example.com/you/app:1
```

## Create the Machine

```shell
tonbo machine create app --image registry.example.com/you/app:1 --shape s-2 --port 8080 --region us-east-1 --wait
```

Words after `--` replace the image’s `CMD`; its `ENTRYPOINT` stays:

```shell
tonbo machine create app --image registry.example.com/you/app:1 --shape s-2 --port 8080 --region us-east-1 --wait -- node server.js --verbose
```

## What runs, and as whom

A Machine runs the image’s `Entrypoint` followed by its `Cmd` (or your command), as the image’s `User`, in its `WorkingDir`, with its `Env` plus `PATH` and `HOME`. The other settings of an [image’s configuration](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md) are not used, its stop signal included: when a sleep signals the program, the signal is `SIGTERM` (see [Stopping](https://tonbo.dev/docs/machines/sleep.md#stop)).

## Environment variables

Up to 128 variables, each named like `LOG_LEVEL` with a value of up to 32,768 characters. A change applies at the next wake:

```shell
tonbo machine update app --env LOG_LEVEL=debug
```

Every member of your account, and every [Agent key](https://tonbo.dev/docs/platform/api-keys.md#key-scope) of it, can read them through the API, and a Machine has no other store for secrets, so put in them only what every member may hold (see [the rule](https://tonbo.dev/docs/machines/rules/access.md#env)).

## What the platform sets

| Variable | What it holds |
| --- | --- |
| `TONBO_DATABASE_URL` | the URL of the Machine’s own database, to pass to open() |
| `TONBO_VFS_CACHE_DIR` | the directory for the database’s local copy, to pass as dir |
| `TONBO_VFS_MAX_PENDING_BYTES` | how much committed data, in compressed bytes, may wait to be sent; pass it as maxPendingBytes |
| `TONBO_REGION` | the Machine’s region |
| `TONBO_MACHINE_NAME` | the Machine’s name |
| `TONBO_MACHINE_ID` | the Machine’s id, which never changes |

The platform sets a few more for the database package itself. Every name it sets is reserved: a Machine whose environment variables set one fails to wake (see [Database wiring](https://tonbo.dev/docs/machines/internals/database.md)). How a program uses the database’s variables is on [Keep data in its database and Volume](https://tonbo.dev/docs/machines/database.md).

## Disks

The program sees the image’s own files with 1 GiB free beyond them, and the shape’s scratch disk at `/scratch`. Both start empty at every wake, so keep nothing there that must last: keep it in the database or on the Machine’s Volume (see [What a wake starts with](https://tonbo.dev/docs/machines/sleep.md#continue)).

## Which images a Machine can use

Public images from a registry reachable over IPv4, within the bounds on [Limits](https://tonbo.dev/docs/machines/limits.md#image). Anyone can pull a public image, so build no secret into it. What Tonbo does with your image is on [Image pulls](https://tonbo.dev/docs/machines/internals/image-pulls.md).