Use the sandbox lifecycle APIs to fetch handles, refresh state, reconnect to a running sandbox, stop it, and expose network ports.
Getting a Sandbox
Fetch a detailed sandbox handle by ID:
const sandbox = await client.sandboxes.get("sandbox-id");
console.log("Sandbox ID:", sandbox.id);
console.log("Status:", sandbox.status);
console.log("Runtime URL:", sandbox.runtime.baseUrl);
console.log("Token expires at:", sandbox.tokenExpiresAt);
get() returns a detailed handle, including the runtime token when the
sandbox is active. list() returns sandbox summaries without runtime-token
fields.
Listing Sandboxes
List your sandboxes with optional filtering:
const response = await client.sandboxes.list({
status: "active",
page: 1,
limit: 20,
});
console.log("Total:", response.totalCount);
for (const sandbox of response.sandboxes) {
console.log(sandbox.id, sandbox.status, sandbox.region);
}
Refreshing and Connecting
Refresh the current handle or reconnect to an existing sandbox:
// Refresh an existing handle
await sandbox.refresh();
// Reconnect from an ID
const reattached = await client.sandboxes.connect("sandbox-id");
console.log(reattached.runtime.baseUrl);
Stopping a Sandbox
Always stop a sandbox when you are done with it:
await sandbox.stop();
console.log("Sandbox stopped");
Stopping a sandbox is safe to call more than once. The control plane treats an
already closed sandbox as a successful stop.
Exposing Ports
Use port exposure when a process inside the sandbox is listening on a network port.
The expose call publishes that port through the sandbox runtime URL.
const exposure = await sandbox.expose({
port: 3000,
auth: true,
});
console.log("Exposed URL:", exposure.url);
console.log("Derived URL:", sandbox.getExposedUrl(3000));
auth is enabled, send the sandbox bearer token when calling the exposed URL:
curl "$EXPOSED_URL" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
Exposing a port only publishes a service that is already running inside the
sandbox. Reserved ports 4001 and 4002 cannot be exposed.
Expose Parameters
Port inside the sandbox to publish.
Require the sandbox runtime bearer token when accessing the exposed URL.
Expose Response
Whether bearer-token authentication is required.
Exposed URL returned by the SDK.
