Sandboxes

A Sandbox is a tenant-owned execution environment that combines a durable mutable filesystem with wakeable AgentOS compute. Use one when an Agent needs the Sandbox-backed file Tool group; Agents without file Tools do not need a Sandbox.

Ownership and attachment

An Agent can have one attached Sandbox, and a Sandbox can be attached to at most one Agent in the same tenant. The Agent's sandboxId and tools configuration determine whether a Turn uses it. Selecting file_operation_sandbox without an attachment fails with SANDBOX_REQUIRED.

The attachment belongs to the Agent, not a Session. The Sandbox retains its workspace across that Agent's Sessions, stateless generation, run-now Tasks, and scheduled Tasks. Sessions reserve no Sandbox compute between Turns.

Create and attach a Sandbox

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({
  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});

const sandbox = await client.sandboxes.create({
  name: "Documentation Sandbox",
});

const agent = await client.agents.create({
  name: "Documentation Agent",
  instructions: "Keep working files in the attached Sandbox.",
  sandboxId: sandbox.id,
  tools: ["file_operation_sandbox"],
});

console.log(agent.sandboxId); // the Sandbox used by later Turns

A later Turn for agent.id can read files written by an earlier Turn because both use the workspace inside the same attached Sandbox.

Workspace and execution model

The Agent loop and model stay in the trusted API or task-worker process. File and command Tool calls cross a private, authenticated transport into the AgentOS actor; provider credentials, prompts, product state, quota, and usage accounting do not move into it.

AgentOS confines writable files to /workspace, denies guest networking and environment access, and applies filesystem, process, descriptor, socket, and WASM compute limits. Rivet identifies the durable actor by Sandbox ID and restores its workspace after sleep or runner replacement.

Each Sandbox admits at most one Turn at a time. One admission covers the full model and Tool loop, while a separate fleet-wide capacity limit bounds all Sandbox Turns. Contending Turns wait in durable queues.

Lifecycle and reuse

Creating a Sandbox creates its product record; the actor starts or wakes only on the first admitted operation. You can update the Sandbox name or metadata. Changing an Agent attachment while it is idle affects later Turns, never one already admitted.

Detach a Sandbox before deleting it. Deletion is rejected while an Agent still uses it, destroys the keyed actor and workspace, and then removes the product row. The SDK returns "completed" when that lifecycle finishes within the request or "pending" while durable deletion continues.

Failure and cancellation

Before file work begins, a Turn waits for both its per-Sandbox admission and global capacity. On success, failure, cancellation, disconnect, or deadline, the platform stops accepting new operations, lets already dispatched operations settle, and confirms actor sleep before releasing capacity.

A failed or canceled Turn is not a filesystem transaction. Mutations that completed before the failure remain in the workspace, and native operations are not replayed blindly. Inspect or repair workspace state on a later Turn when partial work matters.

Production considerations

Use a separate Sandbox for each Agent that needs isolated mutable state.
Keep credentials outside files and commands. Provider credentials remain in the trusted dispatcher and never enter AgentOS.
Expect serialization for Turns sharing one Sandbox and queueing when global capacity is occupied.
Treat command input as untrusted and stay within the fixed network and resource limits of the environment.
Detach before deletion, and account for asynchronous cleanup.
Publish only deliberate deliverables as Artifacts; the workspace itself is never an Artifact.

Reference

Files and outputs overview
Sandbox CRUD: TypeScript SDK and REST API
Agent attachment: TypeScript SDK and REST API
Security and credentials
File operations and Artifacts

On this page