> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent URLs

> Give a hosted agent a stable HTTPS address, serve web apps from its computer, and share private ports with token links.

Every [hosted agent](https://inkbox.ai/docs/capabilities/hosted-agents.md) has its own HTTPS address based on its handle. An agent with the handle `my-agent` is reachable at:

| Address | Serves |
| - | - |
| `https://my-agent.inkbox.sh` | The agent's default port. |
| `https://my-agent--3000.inkbox.sh` | Port `3000` on the agent's computer. |
| `https://my-agent.inkbox.sh/inbound/...` | [Inbound](https://inkbox.ai/docs/capabilities/inbound.md) sources, for webhooks from other services. |

Handles never change, so these addresses never change. Read the base address from `url` on [`GET /hosting`](https://inkbox.ai/docs/api/identities/hosting#read-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](#private-ports)). Add ports and choose a default port with the [ports API](https://inkbox.ai/docs/api/identities/ports.md):

```bash theme={null}
curl -X PATCH https://inkbox.ai/api/v1/identities/my-agent/hosting/ports \
  -H "X-API-Key: $INKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": 1, "default_port": 3000, "ports": [{"port": 3000, "public": false}, {"port": 8080, "public": true}]}'
```

Send the `version` from your last [read](https://inkbox.ai/docs/api/identities/ports.md#read-ports); 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`](https://inkbox.ai/docs/api/identities/ports#rotate-a-port-token), which also returns a new `token_url`:

```text theme={null}
https://my-agent--3000.inkbox.sh/?_token=pt_...
```

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:

```bash theme={null}
curl https://my-agent--3000.inkbox.sh/api/status \
  -H "X-Inkbox-Port-Token: pt_..."
```

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](https://inkbox.ai/docs/capabilities/inbound.md). 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.