# Preview ports
Preview ports let you access web apps and servers running inside a sandbox through an HTTPS URL. They support all HTTP methods and WebSocket connections.
The examples use `$SANDBOX` for the sandbox ID, as in the [quickstart](quickstart.md).
## Open a port
Start your server, then expose its port using `PATCH /v1/sandboxes/{sandbox_id}`.
Ports can only be configured after the sandbox is created. The create request doesn't accept `ports`.
```bash
curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"argv": ["python3", "-m", "http.server", "8000"], "background": true}'
curl -X PATCH https://sandbox.keln.ai/v1/sandboxes/$SANDBOX \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ports": [{"port": 8000}]}'
```
The response includes the sandbox's updated `ports` and `port_token`:
```json
{
"id": "sbx_4k2v9q0m7c1x8z5n3b6d",
"ports": [
{
"port": 8000,
"public": false,
"url": "https://8000-4k2v9q0m7c1x8z5n3b6d.keln.run"
}
],
"port_token": "0123456789abcdefghijklmnopqrstuvwxyz0123"
}
```
This example shows only the relevant response fields. Use the returned `url` rather than constructing it yourself.
Each `PATCH` that includes `ports` replaces the entire list. Include all ports you want to keep open, or send `[]` to close them all.
New ports become available within a second. When closing a port or changing it to private, the API returns once the change takes effect, usually within about a second.
Port `9501` is reserved.
## Private and public ports
Ports are private by default. You can make a port publicly accessible by setting `"public": true`.
| | Private (default) | Public (`"public": true`) |
|---|---|---|
| Access | Requires the sandbox's `port_token` | Anyone with the URL |
| Required header | `X-Keln-Port-Token` | None |
To access a private port:
```bash
curl https://8000-4k2v9q0m7c1x8z5n3b6d.keln.run/ \
-H "X-Keln-Port-Token: $PORT_TOKEN"
```
The `port_token` stays the same for the lifetime of the sandbox. Keep it secret.
Your Keln API key cannot be used to access private ports. Neither the `Authorization` header nor the port token is forwarded to the program running inside the sandbox.
## Cookies on preview URLs
Keln removes the `Domain` attribute from `Set-Cookie` headers returned by your program. This keeps cookies scoped to their individual preview hosts.
!!! note "Preview URLs share one domain"
All preview URLs share the `keln.run` domain, so a script running on another preview can set cookies that browsers send to yours. Don't use cookies received through preview URLs for authentication or other security decisions.
## Limits
| Limit | Value |
|---|---|
| Concurrent connections per sandbox | 256 |
| Concurrent connections per client address | 64 |
| WebSocket message size, in either direction | 1 MiB |
## While the sandbox is paused
Preview ports become unavailable when the sandbox is [paused](pause-resume.md). Existing connections are closed.
The ports become available again when the sandbox resumes.
## Errors
These errors are returned by preview URLs and use the same [error object](../api/sandboxes.md#errors) as the API.
| Code | Meaning |
|---|---|
| `401 invalid_port_token` | The port is private and the request doesn't include a valid `X-Keln-Port-Token`. |
| `404 port_not_found` | The sandbox isn't running or the port isn't exposed. |
| `429 too_many_connections` | The sandbox or client address has reached its connection limit. |
| `503 port_unreachable` | The port didn't respond. Check that a program is listening on it. |
Preview ports
Preview ports let you access web apps and servers running inside a sandbox through an HTTPS URL. They support all HTTP methods and WebSocket connections.
The examples use $SANDBOX for the sandbox ID, as in the quickstart.
Open a port
Start your server, then expose its port using PATCH /v1/sandboxes/{sandbox_id}.
Ports can only be configured after the sandbox is created. The create request doesn't accept ports.
This example shows only the relevant response fields. Use the returned url rather than constructing it yourself.
Each PATCH that includes ports replaces the entire list. Include all ports you want to keep open, or send [] to close them all.
New ports become available within a second. When closing a port or changing it to private, the API returns once the change takes effect, usually within about a second.
Port 9501 is reserved.
Private and public ports
Ports are private by default. You can make a port publicly accessible by setting "public": true.
The port_token stays the same for the lifetime of the sandbox. Keep it secret.
Your Keln API key cannot be used to access private ports. Neither the Authorization header nor the port token is forwarded to the program running inside the sandbox.
Cookies on preview URLs
Keln removes the Domain attribute from Set-Cookie headers returned by your program. This keeps cookies scoped to their individual preview hosts.
Preview URLs share one domain
All preview URLs share the keln.run domain, so a script running on another preview can set cookies that browsers send to yours. Don't use cookies received through preview URLs for authentication or other security decisions.
Limits
Limit
Value
Concurrent connections per sandbox
256
Concurrent connections per client address
64
WebSocket message size, in either direction
1 MiB
While the sandbox is paused
Preview ports become unavailable when the sandbox is paused. Existing connections are closed.
The ports become available again when the sandbox resumes.
Errors
These errors are returned by preview URLs and use the same error object as the API.
Code
Meaning
401 invalid_port_token
The port is private and the request doesn't include a valid X-Keln-Port-Token.
404 port_not_found
The sandbox isn't running or the port isn't exposed.
429 too_many_connections
The sandbox or client address has reached its connection limit.
503 port_unreachable
The port didn't respond. Check that a program is listening on it.