Exposed ports#
An agent that serves a chat UI, a dashboard, or an HTTP API needs a way for people to reach it. An exposed port publishes one container port at a stable URL derived from the sandbox's slug.
curl -fsS -X POST \
-H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
https://agents.example.com/v1/projects/$PROJECT_ID/sandboxes \
-d '{
"image": "ghcr.io/acme/agent:1.2",
"command": "./start.sh",
"cpu": "500m", "memory": "2Gi",
"exposedPorts": [{"name": "web", "port": 8080, "auth": "private"}]
}'
Create a sandbox in production from ghcr.io/acme/agent:1.2 running
"./start.sh" with 500m CPU and 2Gi memory. Publish port 8080 as
"web" with private auth, and give me the URL.
nexusctl sandbox create --project production \
--image ghcr.io/acme/agent:1.2 \
--command "./start.sh" \
--cpu 500m --memory 2Gi \
--port name=web,port=8080,auth=private
Or in a spec file:
exposedPorts:
- name: web
port: 8080
auth: private
A sandbox publishes at most four ports, and auth is decided per port. So one agent can serve an authenticated dashboard and a webhook receiver that admits only signed deliveries from the same container:
exposedPorts:
- name: web
port: 8080
auth: private
- name: hooks
port: 9000
auth: webhook
webhook:
scheme: hmac
header: X-Hub-Signature-256
prefix: "sha256="
secret: ${GITHUB_WEBHOOK_SECRET}
The URL#
Each port answers on its own host, built from the port name and the sandbox slug:
https://<port-name>--<sandbox-slug>.<sandboxIngress.host>
The first entry in exposedPorts also answers on the short host, and that is the URL the platform reports for it:
https://<sandbox-slug>.<sandboxIngress.host>
The slug is assigned at creation and never changes, so a URL is stable across restarts, image upgrades, and rollbacks. The port name is part of the host, so a rename changes the URL.
The short host carries the auth of the first port
The short host serves the first entry in exposedPorts, with that entry's auth. Put a public port first and the short host is open to anyone. Keep the private port first, and let the public port answer on its own named host.
Read the URLs back from the sandbox:
curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
https://agents.example.com/v1/projects/$PROJECT_ID/sandboxes/$SANDBOX_ID \
| jq -r '.exposedPorts[].url'
What URL is the nightly-refactor sandbox in production serving on?
nexusctl sandbox get nightly-refactor --project production -o json \
| jq -r '.exposedPorts[].url'
The URL is null without sandboxIngress.host
If the install was deployed without sandboxIngress.host, exposed ports still exist but resolve to no URL. Set the value and make sure *.<host> resolves to your ingress. See Install on Kubernetes.
Fields#
| Field | Rules |
|---|---|
name |
Lowercase DNS label fragment, ^[a-z][a-z0-9-]{0,30}$. Unique within the sandbox — it is what a URL resolves by. |
port |
TCP port 1–65535, unique within the sandbox. The supervisor dials it on 127.0.0.1 inside the container. |
auth |
private (the default), public, or webhook, decided per port. |
webhook |
How a webhook port checks its sender. Required with auth: webhook, and allowed only then. See webhook. |
A duplicate name or a duplicate port number is refused, because either one makes an entry unreachable.
A sandbox created before platform 0.27.0 serves one port until it restarts
The data tunnel of an older sandbox cannot address a port by name. Rather than route a request to the listener behind a different port, the ingress answers 502 for a revision that declares more than one port. Restart the sandbox so it picks up the current loader image. A single-port revision is unaffected.
The agent binds the port on loopback inside its own container. Nothing else about the sandbox's network is opened by exposing a port — outbound traffic is still governed by policy, and no other port becomes reachable.
Authentication modes#
private#
Requests must carry a valid platform session. Anyone without one is sent to sign in, and access is checked against the project the sandbox belongs to.
This is the default and the right choice for anything beyond a demo.
The platform tells the app behind the port who is calling, over plain HTTP and WebSocket upgrades alike:
| Header | Value |
|---|---|
x-forwarded-user |
The caller's email, or their user id where there is no email. |
x-forwarded-user-id |
The OIDC subject of a signed-in person — the id the rest of the platform keys a user by. |
x-forwarded-user-display-name |
The person's name to display, percent-encoded UTF-8. |
x-forwarded-token-id |
The ID of the API token the caller presented, the same ID the API and the audit trail use. |
The display name is encoded every time, plain ASCII included — Ada Lovelace arrives as Ada%20Lovelace — so decode it with decodeURIComponent. The id and display name describe a person, so only an OIDC session carries them. A header whose value the platform does not know is left off rather than sent empty.
A caller with an API token is not a person, so it gets x-forwarded-token-id and none of the person headers. For a session from workload identity federation, it is the ID of the federated token the session acts as, which stays the same while the hourly sessions rotate. The token's name is not sent. An app that accepts a path from one service only can compare this header with that service's token ID.
Every inbound copy of these headers is stripped on every port before the platform writes its own, along with the identity headers of common identity-aware proxies in front of the install. The app reads the platform's answer or nothing — never what a client claimed. A public port carries none of them. The Authorization header is a platform credential on a private port, so the app does not receive it.
Calls from another origin#
The browser session cookie counts only on a request with no Origin, such as a page navigation or a non-browser client, or on a request from the origin of a private port of the same sandbox. A page on any other origin, a public port of the same sandbox included, must send a platform token as Authorization: Bearer.
For a web app served somewhere else, list its origins in the Helm value sandboxIngress.corsOrigins:
sandboxIngress:
corsOrigins:
- https://app.example.com
- http://localhost:*
Each entry is scheme://host[:port], or scheme://host:* for any port. No other wildcard is accepted, and an invalid entry stops the server from starting. The ingress then answers the CORS preflight to a private port from those origins, allowing Authorization and Content-Type, and adds CORS headers to the errors it returns itself. The app behind the port must set Access-Control-Allow-Origin on its own responses, or the browser does not let the page read them.
public#
The URL opens with no platform session at all. Anyone who has the URL can reach the service.
The app receives the request's Authorization header, so it can check its own bot tokens. A public port forwards a CORS preflight to the app too.
Use public for a local trial, a demo, or a service that does its own authentication. Treat the URL as a secret, and remember that the agent behind it is running with real credentials and real access. For a webhook sender that signs its deliveries or sends a shared token, use webhook instead.
webhook#
A webhook port admits only a request that proves it comes from the sender, by a shared token or an HMAC signature of the body, and checks it before the request reaches the sandbox. The port names the header its sender uses and how to compare it, so it works with any sender rather than a fixed list.
printf '%s' "$GITHUB_WEBHOOK_SECRET" > hooks.secret
nexusctl sandbox create --project production \
--image ghcr.io/acme/agent:1.2 \
--command "./start.sh" \
--cpu 500m --memory 2Gi \
--port name=hooks,port=9000,auth=webhook,scheme=hmac,header=X-Hub-Signature-256,prefix=sha256= \
--webhook-secret-file hooks=hooks.secret
curl -fsS -X POST \
-H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
https://agents.example.com/v1/projects/$PROJECT_ID/sandboxes \
-d '{
"image": "ghcr.io/acme/agent:1.2",
"command": "./start.sh",
"cpu": "500m", "memory": "2Gi",
"exposedPorts": [{
"name": "hooks", "port": 9000, "auth": "webhook",
"webhook": {"scheme": "hmac", "header": "X-Hub-Signature-256",
"prefix": "sha256=", "secret": "<the sender'"'"'s secret>"}
}]
}'
The secret is never a flag value: --webhook-secret-file NAME=PATH reads it from a file, or - for stdin. In a spec file, use secret: ${VAR}. In the admin UI, choose Webhook (verified sender) for the port.
| Field | Rules |
|---|---|
scheme |
token: the header carries the secret itself. hmac: the header carries an HMAC of the raw request body under the secret. |
header |
The header that carries the token or signature, matched case-insensitively. |
prefix |
Optional text before the value, such as sha256=, v1=, or Bearer. A value without it is accepted too. |
algorithm |
hmac only: sha256 (default), sha1, or sha512. |
encoding |
hmac only: hex (default) or base64. |
signedUrl |
hmac only, optional: for a sender that signs the body followed by its webhook URL. The exact URL set in the sender. |
secret |
Write-only. Required when the port has no secret yet; an update without it keeps the stored one. A read returns only secretSet. |
| Sender | scheme |
header |
prefix |
|---|---|---|---|
| GitHub | hmac |
X-Hub-Signature-256 |
sha256= |
| GitLab | token |
X-Gitlab-Token |
|
| PagerDuty | hmac |
X-PagerDuty-Signature |
v1= |
| Alertmanager | token |
Authorization |
Bearer |
| Trello | hmac |
X-Trello-Webhook |
Trello also needs algorithm: sha1, encoding: base64, and signedUrl set to its callback URL.
What the port answers:
- A request that fails the check gets
401 Webhook sender verification failed, and so does every request while the port has no secret. Each refusal is written to the audit trail assandbox.expose.request, withwebhookAuthinvalidormisconfiguredinmetadata. - An
hmacbody over 1 MiB gets413, because the body is read whole before it is checked. HEADgets200without a credential and without reaching the sandbox, for senders that probe the URL before saving it. A WebSocket upgrade is refused. A sender that verifies its URL with an unsignedGETchallenge cannot pass the check; give it apublicport.- The app receives the request with
x-nexus-webhook-verified: 1. A token is removed, because it is the secret; a signature is kept, so the app can check it too. Any copy ofx-nexus-webhook-verifieda caller sent is removed.
Once a request passes, the port behaves like public: it carries no identity headers, it does not count as activity, and it does not start a stopped sandbox.
Rotate the secret#
The secret is not part of the revision, so changing it restarts nothing. The next request is checked against the new secret.
printf '%s' "$NEW_SECRET" | nexusctl sandbox webhook-secret nightly-refactor hooks \
--project production
curl -fsS -X PUT \
-H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
https://agents.example.com/v1/projects/$PROJECT_ID/sandboxes/$SANDBOX_ID/exposed-ports/hooks/webhook-secret \
-d '{"secret": "<the new secret>"}'
It needs project admin. nexusctl reads the secret from stdin or --from-file, never from the command line. An hmac header may carry several comma-separated signatures, and the request passes if any one matches, so a sender that signs with both secrets during its rotation keeps working. A rollback keeps the current secret. Removing the port, or moving it off webhook, deletes its secret, and a rollback to a webhook port without one is refused. Exporting a sandbox leaves the secret out.
Health checks pair with exposed ports#
A sandbox that serves HTTP is usually worth probing. Point an HTTP health check at the same port so the platform can tell "running" from "running and answering":
exposedPorts:
- name: web
port: 8080
auth: private
healthCheck:
type: http
http:
path: /healthz
port: 8080
Related#
- Sandbox spec — declaring ports in a file
- Storage and health — probes, revisions, and rollback
- Install on Kubernetes — wildcard ingress for
*.<sandboxIngress.host> - Sandbox isolation — what an exposed port does not open up