Open sessions

A session is a scoped, expiring connection to a running service or sandbox. Simple service use needs no session — start the service and let your app use the named dependency. Sessions exist for the interactive cases: a stdio stream into a running workload, file exchange, or a browser-control channel. A session is a lease, not an ambient connection that outlives its purpose.

All examples assume a configured client:

import { Nimbus } from "@nimbus/nimbus";

const nimbus = new Nimbus({
  endpoint: "http://localhost:8080",
  tenantId: "demo",
  token: process.env.NIMBUS_TOKEN,
});

Open a session

const session = await nimbus.sessions.open({
  target: { service: { name: "worker" } }, // or { sandbox: { id: "..." } }
  channels: ["stdio"],                     // "cdp" | "page" | "stdio" | "files"
  requestedTtlMs: 10 * 60 * 1000,
});

console.log(session.metadata.id, session.spec.expiresAt);

A session targets exactly one service (by name) or one sandbox (by id) — never both, never neither. A sandbox target must be in the ready state.

Declare the right channels

Channels are declared up front and validated against what the target can actually offer:

Target	Channels
Sandbox, or sandbox-backed service	stdio, files
Built-in browser service	cdp, page
Other built-in providers, external services	none

Set the TTL and close when done

The requested TTL is optional; the server applies a default of fifteen minutes and caps every session at one hour. Sessions move through open, closed (explicitly closed, with a recorded reason), and expired states:

const open = await nimbus.sessions.list({ state: "open" });

await nimbus.sessions.close({ id: session.metadata.id, reason: "done" });

Check what the session attached to

The response’s spec.targetSnapshot records exactly what the session attached to — the service name or sandbox id, its generation, and its backend at open time. Opening against a dynamic service whose definition changed mid-open is rejected as a conflict rather than silently attaching to something else.

Opening is also an authorization event: a service-targeted session needs an exact grant for that service name, a sandbox-targeted session needs reach to that specific sandbox id, and opens, lookups, and closes are recorded as audit events.

Error handling

SDK calls surface the server’s structured errors — see the error reference for the code catalog. The underlying HTTP endpoints are listed in the HTTP API reference if you need to call them without the SDK.

Related pages

• Run sandboxes — creating the targets sessions attach to.
• Manage services — named targets and readiness.
• Services, sandboxes, and sessions — why sessions are leases.