Introduction

A sandbox for the AI SDK's HarnessAgent that runs on your real filesystem and processes.

ai-sandbox-local lets an AI SDK HarnessAgent drive a coding CLI (Claude Code, Codex, OpenCode, pi) against a repo that is already on your machine. There is no VM, container, or remote sandbox in between.

You have a repo on disk and want to start an agent on it from your own code: a script, a desktop app, a CI job. HarnessAgent needs a sandbox to run the CLI in, and neither of the two it ships fits:

@ai-sdk/sandbox-vercel runs in a remote Vercel Sandbox. Your checkout isn’t there.
@ai-sdk/sandbox-just-bash is a JavaScript bash over an in-memory filesystem. It exposes no ports, and the bridge that the CLI-backed harnesses use to talk to the host needs one.

This package is the third option: a directory on your disk, /bin/bash, and a leased loopback port.

Where to go next

Getting started

Install it and run an agent on a repo.

Working directory and $HOME

Where the agent works and where harness state lands.

Configuration

Environment variables, PATH for GUI apps, pnpm build approval.

Sessions and processes

run, spawn, ports, and shutdown.