sandboxes

Expose a port inside a sandbox at a public HTTPS URL - the preview URL for a dev server [rate class: sandbox_api_rps]

Expose a port inside one of your SANDBOXES at a public HTTPS URL - the preview URL for a dev server, so the page an agent just wrote can be looked at (or curled, or driven by a browser) from outside. Returns {endpoint_id, url, sandbox, port, auth, expires_at}. Default auth is the capability URL itself: the hostname carries an unguessable secret, so anyone holding the URL reaches the port - treat it like a password. auth:"bearer" additionally requires Authorization: Bearer <token> at the edge; that token rides the response ONCE. THE SERVER HAS TO BE RUNNING AND ON LOOPBACK: bind 127.0.0.1 (the dev-server default) on a port in 1024-65535, and background it WITH ITS OUTPUT REDIRECTED - (npm run dev > /tmp/dev.log 2>&1 &) - because sandbox_exec waits for a command's output to end, so a bare npm run dev & hangs the exec and then dies with it. Exposing a port nothing listens on succeeds; the URL then answers 502 naming the port, so start the server first. Idempotent per (sandbox, port): the same call returns the same URL with a refreshed expiry, which makes it cheap to call in a loop. The endpoint belongs to THIS sandbox: a fork does not inherit it (a fork is a new sandbox - expose its own port), and deleting the sandbox kills the URL. An inbound request wakes a parked sandbox, so traffic puts it back on the active RAM tier. Raw byte pipe behind the URL: streaming, SSE and WebSocket all pass through. No vanity hostnames on sandbox endpoints (nodes have those); works even on a sandbox with egress:"none", because nothing dials out to serve it.

post/preview/sandboxes/{id}/expose

Request

  • Base URL: https://autoresearch.sfcompute.com
  • URL: https://autoresearch.sfcompute.com/preview/sandboxes/{id}/expose
  • Auth: HTTP bearer

Path parameters

idstring required

The sandbox whose port to expose. Opaque - pass back the exact string create_sandbox / fork_sandbox gave you.

Query parameters

workspacestring

Act in this workspace (its slug). Omitted: the token's bound workspace, then the organization's default. Never ambient - there is no switch-workspace mutation on this door.

Request body

authstring nullable

"capability-url" (the default: the unguessable URL is the secret) or "bearer" (also require Authorization: Bearer <token> at the edge; the token rides the response once).

portinteger required

The port the server inside the sandbox listens on, 1024-65535 (a dev server's 3000, 5173, 8000). It must be bound on the sandbox's LOOPBACK, which is what dev servers bind by default.

Response

The capability's JSON result.

objectstring

The resource type, when the result is one resource.

Changes

No recorded changes to this operation across all 1 revision of this API.