AI SDK - Local Sandbox

This package is experimental.

HarnessV1SandboxProvider implementation backed by the local machine.

[!WARNING] This provides no isolation. The agent runs commands and edits files directly on the host, with the host process's permissions. Use it only where the host is itself the trust boundary: your own machine, or a disposable container or VM you control. For real isolation, run against a remote or containerized sandbox provider.

Setup

npm i ai-sdk-sandbox-local @ai-sdk/harness

Usage

The factory is synchronous. The returned provider is stable; a session, rooted at a working directory on the host, is created inside provider.createSession().

import { createLocalSandbox } from 'ai-sdk-sandbox-local';

const localSandbox = createLocalSandbox({ cwd: process.cwd() });

const networkSandboxSession = await localSandbox.createSession();
const sandboxSession = networkSandboxSession.restricted();

await sandboxSession.writeTextFile({ path: 'hello.txt', content: 'hi' });

const { stdout } = await sandboxSession.run({ command: 'cat hello.txt' });
console.log(stdout); // "hi"

await networkSandboxSession.stop();

networkSandboxSession.restricted() is typed as Experimental_SandboxSession, so it is safe to pass to AI SDK tools that accept experimental_sandbox. The network sandbox session itself carries the infra surface (ports, getPortUrl, setPorts, setNetworkPolicy, stop) that only the harness should reach for.

Configuration

The environment is the host's, so the session inherits process.env. There are no credentials to resolve; the two settings shape where and how it runs.

const localSandbox = createLocalSandbox({
  cwd: '/path/to/repo', // working directory; defaults to process.cwd()
  ports: [3000], // pin a bridge port; by default one is leased
});

• cwd the working directory the session is rooted at. Relative paths in file operations resolve against it. Defaults to process.cwd().
• ports ports to pre-expose. The harness leases a bridge port via setPorts, and on localhost exposing is a no-op, so this is usually unnecessary. Set one to pin a fixed bridge port.

Per-command environment and working directory are set on each call, not on the provider:

await sandboxSession.run({
  command: 'echo $GREETING',
  env: { GREETING: 'hi' },
  workingDirectory: 'packages/app',
});

Resuming

The host persists, so resumeSession({ sessionId }) rebinds to the same cwd for a given session id without recreating anything.

Ports and network policy

getPortUrl resolves to http://127.0.0.1:<port> and throws HarnessCapabilityUnsupportedError for a port that was never exposed. There is no network boundary to enforce, so setNetworkPolicy is a no-op. For real egress control, run against an isolating provider.

License

Apache-2.0