my-agent is reachable at:
Handles never change, so these addresses never change. Read the base address from
url on GET /hosting.
Use ports to serve a dashboard, a preview of something the agent built, or an API for other tools. The agent runs the server on its computer; Inkbox handles HTTPS. WebSockets work too.
A request wakes a sleeping computer and starts one that stopped after being idle. Inkbox holds the request for up to 60 seconds while the computer starts; if it isn’t ready by then, the request gets 503 with code warming, and a retry shortly after succeeds. If you stopped the computer yourself, requests get 409 until you start it again.
Expose a port
Token links and public access work only for ports you add. An Inkbox API key with access to the agent can reach any port, listed or not (see Private ports). Add ports and choose a default port with the ports API:version from your last read; if someone changed the ports since, the update returns 409 with code stale_version. The default port must be one of the listed ports. Without a default port, https://my-agent.inkbox.sh returns 404.
Port addresses are available for handles up to 56 characters. For a longer handle, ports have no address of their own and their url is null. A long handle can still use its default port at the base address.
Private ports
Ports are private by default. A request to a private port needs one of:- The port’s token, in the
_tokenquery parameter or theX-Inkbox-Port-Tokenheader. - An Inkbox API key with access to the agent, in the
X-API-Keyheader. An API key reaches any port on the agent’s computer, including ports you haven’t exposed.
token_url once. Replace a port’s token with POST /hosting/ports/{port}/token, which also returns a new token_url:
_token. Later page loads and links on that address work without the token in the URL.
For scripts and other services, send the header instead:
Public ports
Set"public": true on a port to make it reachable by anyone without a token. Public ports are rate-limited per agent; excess requests get 429.
What reaches your app
Inkbox removes the port token and your Inkbox API key before forwarding a request. Your app receives other headers, includingAuthorization and Cookie, and its Set-Cookie responses reach the browser. Your app can run its own sign-in on top of a private or public port.
Request bodies sent to a port can be up to 512 KiB.
Inbound webhooks
The/inbound/ path on the base address is reserved for Inbound. Inbound accepts webhooks from other services even while the computer is stopped, without exposing a port.
Management stays on the API
Agent URLs serve only your agent’s apps and Inbound. Manage the agent, its computer, and its files throughhttps://inkbox.ai/api/v1.
