Local

Local provides the normalized Sandbox SDK API without a cloud account. It is an AgentOS VM, not a Linux container.

Installation

Terminal

bun add @opencoredev/sandbox-sdk ai zod

Local supports Node.js 22 and 24, and Bun 1.3 or newer.

Authentication

No credentials are required.

Run a command

local.ts

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { local } from "@opencoredev/sandbox-sdk/local";

await using sandbox = await createSandbox({ provider: local() });
const result = await sandbox.run("node --version");
console.log(result.stdout);

Run an AI SDK agent

This provider works with AI SDK ToolLoopAgent through the normalized sandbox session. Pass the language model from your existing AI SDK provider or AI Gateway setup.

sandbox-agent.ts

import { ToolLoopAgent, type LanguageModel } from "ai";import { createSandbox } from "@opencoredev/sandbox-sdk";import {  createSandboxToolApproval,  createSandboxTools,  toAISandboxSession,} from "@opencoredev/sandbox-sdk/ai";import { local } from "@opencoredev/sandbox-sdk/local";export async function runSandboxAgent(model: LanguageModel) {  await using sandbox = await createSandbox({    provider: local(),  });  const aiSandbox = toAISandboxSession(sandbox);  const agent = new ToolLoopAgent({    model,    instructions: `Work only in the provided sandbox.\n\n${aiSandbox.description}`,    tools: createSandboxTools(),    toolApproval: createSandboxToolApproval(),  });  return await agent.generate({    prompt: "Inspect the repository, run its tests, and summarize the result.",    experimental_sandbox: aiSandbox,  });}

See the AI SDK guide for approval flows, direct session access, and HarnessAgent alternatives.

Files and processes

workspace.ts

await sandbox.files.write("index.mjs", `console.log("ready")`);
const process = await sandbox.processes.start("node index.mjs");

for await (const event of process.output()) {
  console.log(event.data);
}

Local supports background processes, stdin, cancellation, and combined output streams.

Ports and snapshots

ports.expose() bridges requests into the VM without publishing a host port. Local snapshots support create, restore, and delete within the current host process.

snapshot.ts

const snapshot = await sandbox.snapshots.create({ name: "prepared" });
await sandbox.snapshots.restore(snapshot);

Options

Option	Type	Default	Behavior
`agentOs`	`AgentOsOptions`	SDK policy and limits	Configures the native AgentOS VM.

Behavior

Outbound internet and host bindings are denied by default. Native agentOs.permissions replace the complete default policy.
The guest is WebAssembly/V8-based. Do not assume Docker, browsers, package managers, or arbitrary Linux executables are available.
Sandboxes, suspended sessions, and snapshots live only as long as the host process.
sandbox.raw provides typed access to the current AgentOS VM.

Beta runtime

AgentOS is beta. Your application still owns authentication, authorization, quotas, host hardening, secrets, and cleanup.