Sandbox Agents

SandboxAgent extends Agent with a workspace and four built-in tools for file and command operations:

sandbox_read_file
sandbox_write_file
sandbox_list_files
sandbox_run_command

Use it when an agent needs to inspect or modify files without giving tools access to your whole filesystem.

Quick Start

sandbox-agent.ts

import { LocalSandbox, SandboxAgent, run } from "@usestratus/sdk/core";

const sandbox = new LocalSandbox({
  root: "/tmp/stratus-workspace",
  commandTimeoutMs: 30_000,
  maxOutputBytes: 64 * 1024,
});

const agent = new SandboxAgent({
  name: "workspace-agent",
  model,
  sandbox,
  instructions:
    "You can read, write, list, and run commands inside the workspace.",
});

const result = await run(
  agent,
  "Create README.md with a short project summary.",
);
console.log(result.output);

You can also pass LocalSandboxOptions directly:

const agent = new SandboxAgent({
  name: "workspace-agent",
  model,
  sandbox: { root: "/tmp/stratus-workspace" }, 
});

Workspace API

LocalSandbox confines file paths to the configured root. Attempts to read or write outside the root throw.

await sandbox.writeFile("notes/todo.md", "- ship docs");
const text = await sandbox.readFile("notes/todo.md");
const files = await sandbox.listFiles(".");
const result = await sandbox.runCommand("ls -la");

Method	Description
`readFile(path)`	Read a UTF-8 file from the workspace
`writeFile(path, content)`	Write a UTF-8 file, creating parent directories
`listFiles(path?)`	Recursively list files under a path
`runCommand(command, options?)`	Run a shell command with `cwd` set to the workspace root

runCommand() returns:

interface CommandResult {
  exitCode: number | null;
  stdout: string;
  stderr: string;
}

Configuration

Option	Type	Description
`root`	`string`	Required. Workspace root directory
`commandTimeoutMs`	`number`	Default command timeout in milliseconds. Defaults to `30000`
`maxOutputBytes`	`number`	Maximum combined stdout/stderr returned. Defaults to `65536`

Custom Tools

SandboxAgent accepts all normal AgentConfig fields. Your own tools are appended after the sandbox tools:

const agent = new SandboxAgent({
  name: "builder",
  model,
  sandbox: { root: "/tmp/build" },
  tools: [publishArtifact],
});

Disable built-in sandbox tools if you want to provide a narrower tool set:

const agent = new SandboxAgent({
  name: "read-only",
  model,
  sandbox: { root: "/tmp/work" },
  includeSandboxTools: false, 
  tools: [readProjectSummary],
});

LocalSandbox confines paths and command working directory, but it is not a VM or container security boundary. Commands still execute as the current OS user. For untrusted code, use a real container, VM, or remote execution service behind a custom SandboxWorkspace.

Quick Start

Workspace API

Configuration

Custom Tools

On this page