Agents

Nimbus gives AI agents isolated compute next to their data through three resources — sandboxes, services, and sessions — managed through the @nimbus/nimbus SDK or plain HTTP. The sandbox quickstart is the fastest way in; the resource model explains the design.

Sandboxes execute on a Linux host. On macOS or WSL2, run nimbus machine first to start the managed Linux VM that hosts them — see the CLI reference.

The shape to remember: reach for a sandbox when an agent needs an isolated world for one task — it has an id, a lifecycle, and session access, and it disappears without leaving a name behind. Promote work to a service only when other code should depend on it by name. Open a session when something needs to interact with a running resource under a lease that expires on its own. The design rationale behind the three nouns is explained in Services, sandboxes, and sessions.

Start here

• Agent sandbox quickstart — create a sandbox, wait for it to come up, open a session, and tear it down, in about five minutes.
• Run sandboxes — standalone sandboxes: specs, labels, listing, and what the API redacts.
• Manage services — named workloads: backends, readiness waiting, and generation-checked updates.
• Open sessions — channels, TTLs, and target snapshots.

Example agents

Not every agent needs a sandbox. Two runnable examples build agents purely on the native SDK’s document store and scheduler — durable state and self-driven follow-ups, all inside your own deployment:

• Build a durable chat agent — a chat agent that persists its conversation, remembers facts, and schedules its own reminders.
• Run a headless agent worker — an unattended worker that runs a batch of jobs to completion server-side.

Where sandboxes actually run

Sandbox execution runs on Linux hosts, and both backends enforce deny-by-default network egress. Workloads launch as OCI containers by default; libkrun microVMs also execute on Linux and are the default for services run through nimbus compose. On macOS and WSL2, nimbus machine provides the managed Linux VM that hosts them — see the CLI reference. The full status table is in current capabilities.

Ordinary Nimbus functions are not sandboxes: they run in V8 isolates inside the server process and never appear in sandbox listings. The boundary is explained in Services, sandboxes, and sessions.

Going deeper

• Sandboxes and machines — how the isolation seam works under the hood.
• SDK resources reference — every type and method signature.
• HTTP API reference — the wire surface beneath the SDK, for agents that speak plain HTTP.