Skip to main content
Every hosted agent has its own HTTPS address based on its handle. An agent with the handle 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:
Send the 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 _token query parameter or the X-Inkbox-Port-Token header.
  • An Inkbox API key with access to the agent, in the X-API-Key header. An API key reaches any port on the agent’s computer, including ports you haven’t exposed.
Adding a private port returns its shareable token_url once. Replace a port’s token with POST /hosting/ports/{port}/token, which also returns a new token_url:
Store the link when you create it. Later reads don’t include the token. Rotating issues a new token, and the previous token stops working immediately. When a browser opens a token link, Inkbox stores the token in a cookie for that address and redirects to the same URL without _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:
Anyone with a token link can reach that port. Share it only with people and services you trust.

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, including Authorization 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 through https://inkbox.ai/api/v1.