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

# Rules: requests

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.”

Check these rules before you open your Machine to callers: each keeps its requests answered and its bill small.

The examples use the database a Machine opens as [Keep data in its database](https://tonbo.dev/docs/machines/database.md#open) shows, and a `node:http` server.

### Listen on 0.0.0.0, at a port you declare

Tonbo connects to your program from outside the Machine’s loopback, and serves only declared ports (see [Ports and names](https://tonbo.dev/docs/machines/requests.md#ports)).

**Do**

```js
server.listen(8080, "0.0.0.0"); // the Machine was created with --port 8080
```

**Don’t**

```js
server.listen(8080, "127.0.0.1"); // unreachable
```

### Start listening within seconds

A request that wakes the Machine waits only so long for your program to listen, then is answered `503` (see [The first request](https://tonbo.dev/docs/machines/requests.md#first-request)).

**Do**

```js
const db = await open(process.env.TONBO_DATABASE_URL, settings);
server.listen(8080, "0.0.0.0");
warmCaches(db); // in the background, while serving
```

**Don’t**

```js
const db = await open(process.env.TONBO_DATABASE_URL, settings);
await rebuildIndexFromScratch(db); // minutes: every waking request times out
server.listen(8080, "0.0.0.0");
```

### Keep a port private unless it must be public

Anyone can call a public port and wake the Machine, Tonbo limits none of those requests, and every second awake is billed (see [Public ports](https://tonbo.dev/docs/machines/requests.md#public-ports) and [the example](https://tonbo.dev/docs/machines/pricing/examples.md#private-port)).

**Do**

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

**Don’t**

```shell
tonbo machine create tools --image registry.example.com/you/tools:1 --shape s-1 --port 8080:public # an internal tool anyone can wake
```

### Check your own users’ credentials on a public port only

On a private port Tonbo checks the caller’s key and removes `Authorization` before your program sees it; on a public port the header passes through (see [Private ports](https://tonbo.dev/docs/machines/requests.md#private-ports)).

**Do**

```js
// On a public port: your program checks its own users.
const user = await verifyUser(req.headers.authorization);
```

**Don’t**

```js
// On a private port: Tonbo removed the header.
const user = await verifyUser(req.headers.authorization); // always undefined
```

### Call a private port with a personal key or an exchanged token

A private port takes a member’s personal key, or an access token exchanged from an [Agent’s key](https://tonbo.dev/docs/platform/api-keys.md#key-scope), and refuses the Agent’s key itself (see [The token exchange](https://tonbo.dev/docs/platform/api-keys.md#exchange)).

**Do**

```shell
curl -H "Authorization: Bearer $TONBO_API_KEY" https://tools-<account>.tonbo.sh/
```

**Don’t**

```shell
curl -H "Authorization: Bearer $AGENT_KEY" https://tools-<account>.tonbo.sh/ # 401 exchange_required
```

### Retry a 503 after its Retry-After

A wake still under way, an image still being pulled and a full host answer `503` with `Retry-After`, and the request did not run (see [Troubleshooting](https://tonbo.dev/docs/machines/troubleshooting/call.md#machine_waking)); [curl --retry](https://curl.se/docs/manpage.html#--retry) waits as told.

**Do**

```shell
curl --retry 5 https://tools-<account>.tonbo.sh/
```

**Don’t**

```shell
curl https://tools-<account>.tonbo.sh/ || exit 1 # gives up on a Machine that is waking
```