Serve requests

Last updated 2 November 2026

Decide who may call your Machine and how, when your program starts serving requests: each port’s address, private and public ports, and what reaches your program.

Ports and names

Your program listens on 0.0.0.0 at a port the Machine declares. The default port answers at the Machine’s name, https://tools-<account>.tonbo.sh, and any other at its own name, such as https://p9000--tools-<account>.tonbo.sh. A Machine declares up to 8 ports; 22 and 1023 are Tonbo’s. A change of ports applies at once.

Private ports

A private port takes Authorization: Bearer with a key of a member of the Machine’s account. A member’s personal key works as it is. The key of an Agent, an identity of your account with keys of its own, is exchanged for an access token first, and the token is sent instead; a token expires, so a client exchanges the key again before it does (see The token exchange). A key narrowed to databases or streams is refused.

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

Tonbo removes Authorization before the request reaches your program, so your program cannot learn which key called it.

An MCP server for your agents that speaks streamable HTTP fits a private port when its client sends a bearer header, and a public port when it checks its own users’ credentials.

Public ports

Anyone can call a public port, and any request to it can wake the Machine. Tonbo limits neither how often, how many at once nor for how long, and every second the Machine is awake is billed (see the example). Making a port public needs an owner or admin. Authorization reaches your program unchanged, so a public port can check your own users’ credentials (see the rule).

What reaches your program

HTTP/1.1, Server-Sent Events (the HTML standard’s event streams) and WebSocket. Clients may use HTTP/2 to Tonbo, which forwards HTTP/1.1, so gRPC is not served. TLS ends at Tonbo, and X-Forwarded-For carries the caller’s address, with X-Forwarded-Host and X-Forwarded-Proto beside it. The path a request takes is on Network path.

The first request after a sleep

It waits while the Machine starts and your program begins to listen, at most for the bound on Limits, and is then answered 503 with Retry-After (see the Machine is still starting). The wait includes the cold start of its database when your program opens it before it listens. A caller on a public port gets the same 503 for any refusal, without the reason (see a refusal on a public port). Start listening within seconds of starting (see the rule).

Open requests keep it awake

A request, a Server-Sent Events response or a WebSocket keeps the Machine awake for as long as it is open, whatever it carries, and that time is billed. Once the last one closes, the Machine goes to sleep after its sleep-after time (10 minutes by default) or sooner (see When it sleeps).