Skip to content

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.

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:

{
  "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:

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.

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.