Sandbox and extend the coding tools

Your agent must work on files that are not on this machine, or on code that you do not trust. Or you want code to run after each write, like a formatter. The coding tools send every read, write, and command through a backend, and they run hooks after each read and write. This page shows how to change both.

Run the tools in a sandbox#

By default, the tools run on your machine, with the rights of your user. For code that you do not trust, run them in a sandbox. sandboxWorkspaceBackend() sends every read, write, and command to the sandbox.

1. Install the sandbox packages:

npm i @tanstack/ai-sandbox @tanstack/ai-sandbox-docker

pnpm add @tanstack/ai-sandbox @tanstack/ai-sandbox-docker

yarn add @tanstack/ai-sandbox @tanstack/ai-sandbox-docker

bun add @tanstack/ai-sandbox @tanstack/ai-sandbox-docker

2. Start a sandbox, and give its backend to workspaceTools():

import { defineHarness } from '@tanstack/ai-harness'
import { permissions } from '@tanstack/ai-harness/plugins'
import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
import { openaiText } from '@tanstack/ai-openai'
import { sandboxWorkspaceBackend } from '@tanstack/ai-sandbox/harness'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'

const sandbox = await dockerSandbox({ image: 'node:22' }).create({})
// Without `dir`, the clone goes to the workspace root, /workspace.
await sandbox.git.clone({ url: 'https://github.com/acme/web-app.git' })

const root = '/workspace'

export const sandboxed = defineHarness({
  name: 'acme/sandboxed-coder',
  adapter: openaiText('gpt-6.1-sol'),
  plugins: () => [
    permissions({ root }),
    workspaceTools({ root, backend: sandboxWorkspaceBackend(sandbox) }),
  ],
})

To give the agent the project folder on your machine, copy it into the container.

3. When you are done, stop the sandbox with await sandbox.destroy().

Every provider works. Get the handle from create(), or from resume() for a sandbox that runs already. See Providers. To create a sandbox for each thread, and resume it on another server, see Run the coding tools for many threads.

In a sandbox, some things are different:

• Paths are POSIX paths in the sandbox, like /workspace/src/a.ts, also on a Windows host.
• The tools check where links lead with lstat and readlink in the sandbox. A sandbox without lstat cannot find links, so the tools refuse every path.
• background: true needs a sandbox with capabilities.backgroundProcesses.
• A sandbox with capabilities.killableProcesses off cannot stop a command after the time limit. The call returns, and the command continues in the sandbox.
• list_files and grep use rg in the sandbox. The @vscode/ripgrep binary is a host file, so the sandbox does not use it.
• When the run stops, the file calls of a tool in the sandbox get the abort signal too, so they stop with the run.

Copy your project into the container#

A clone has only the commits that you pushed. To give the agent your project as it is now, copy its folder into the container. In step 2, replace the create({}) and git.clone() lines with this code:

import { defineWorkspace, localSource } from '@tanstack/ai-sandbox'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'

// Run this script in the root folder of your repository.
const sandbox = await dockerSandbox({ image: 'node:24' }).create({
  workspace: defineWorkspace({ source: localSource(process.cwd()) }),
})

The tools now work on your project in /workspace.

• The copy has every file that git does not ignore, with its uncommitted changes. Ignored files, like node_modules, stay on your machine, so install the dependencies in the container.
• The copy has the current branch with its history, so git status in the container shows your uncommitted changes. Staged changes show as unstaged.
• The folder must be the root of a git repository or a git worktree, and not a shallow clone. Otherwise, create() throws before it starts a container.
• Your machine and the image both need git. node:24 has git, and alpine does not.
• create() copies the folder once. Your folder does not get the changes that the agent makes in the container.

Write your own backend#

A WorkspaceBackend is where the tools read and write files and run commands. Write one for another place, for example a remote machine. Every path that the tools give it is absolute.

The backend must have:

• exec resolves with the exit code of a command that fails. It does not throw.
• After options.timeoutMs, exec stops the command with every process that it started, and gives exit code 124. options.signal stops it too.
• options.env holds the variables to add. Give a command only these and the few variables that it needs to start. Do not give it the variables of your server.
• When realpath throws, the tool call fails. So a path with a link that the backend cannot resolve is never used.
• Each file method gets an optional last argument, { signal }. It is the abort signal of the tool call. Give it to your file calls, so a stopped run stops them too. readLines gets signal in its options.

The backend can also have:

For background jobs and for threads that move to another server:

close must never destroy a sandbox that the backend did not create.

The fastest start is to wrap hostBackend. This backend logs each command before it runs:

import { hostBackend, workspaceTools } from '@tanstack/ai-harness/plugins/coding'
import type { WorkspaceBackend } from '@tanstack/ai-harness/plugins/coding'

const root = process.cwd()

const logged: WorkspaceBackend = {
  ...hostBackend,
  exec: (command, options) => {
    console.log(`$ ${command}`)
    return hostBackend.exec(command, options)
  },
}

export const loggedTools = workspaceTools({ root, backend: logged })

Only hostBackend itself uses the @vscode/ripgrep binary. A wrapped backend uses rg on the PATH.

Run code after a read or a write#

Another plugin can add code that runs after the tools read or write a file. Add a WorkspaceHooks item:

import { definePlugin } from '@tanstack/ai-harness'
import { WorkspaceHooks } from '@tanstack/ai-harness/plugins/coding'

export const generatedFiles = definePlugin({
  name: 'acme/generated-files',
  setup: () => ({
    contribute: [
      WorkspaceHooks.item({
        afterRead: async (path) =>
          path.endsWith('.gen.ts')
            ? 'This file is generated. Change its source, not this file.'
            : undefined,
        afterWrite: async (path) => {
          console.log(`changed ${path}`)
        },
      }),
    ],
  }),
})

• afterRead gets the absolute path. The text that it gives is added after the lines that read_file shows.
• afterWrite runs after write_file, edit_file, and patch.
• A hook runs while the tool holds the lock on that path. A hook that throws fails the tool call.

Add the plugin next to the tools: plugins: () => [workspaceTools({ root }), generatedFiles].

Refuse a write#

Add a beforeWrite hook to stop a write before it changes a file. Return { refuse }, and the tool call fails with that text:

import { definePlugin } from '@tanstack/ai-harness'
import { WorkspaceHooks } from '@tanstack/ai-harness/plugins/coding'

export const protectGenerated = definePlugin({
  name: 'acme/protect-generated',
  setup: () => ({
    contribute: [
      WorkspaceHooks.item({
        beforeWrite: async (path) =>
          path.endsWith('.gen.ts')
            ? { refuse: `${path} is generated. Change its source.` }
            : undefined,
      }),
    ],
  }),
})

• beforeWrite gets the absolute path. It runs before write_file, edit_file, and patch change the file.
• A patch asks for each file that it changes before its first write. One refusal fails the whole patch, and no file changes.
• The hook runs before the tool takes the lock on the path.

Format each file after a write#

The model writes code that your formatter changes later, and the diff gets noisy. formatter() formats each file that the tools write:

import { defineHarness } from '@tanstack/ai-harness'
import { permissions } from '@tanstack/ai-harness/plugins'
import { formatter } from '@tanstack/ai-harness/plugins/coding'
import { openaiText } from '@tanstack/ai-openai'

export const formatted = defineHarness({
  name: 'acme/formatted-coder',
  adapter: openaiText('gpt-6.1-sol'),
  plugins: () => [
    permissions({ root }),
    workspaceTools({ root }),
    formatter({ root }),
  ],
})

At the first write of a session, formatter() looks at the files in root. For each file, the first formatter that the project uses for that file type runs.

For JavaScript, TypeScript, JSON, CSS, and other web files:

These three run with npx --no-install, so the project must have them installed.

For other languages:

Add your own formatter. Your formatters come before the built-in ones:

export const withToml = formatter({
  root,
  formatters: [
    {
      name: 'taplo',
      extensions: ['.toml'],
      command: (file) => `taplo fmt ${file}`,
    },
  ],
})

• command gets the absolute path, already quoted for the shell.
• when(project) limits a formatter to some projects. Without it, the formatter is used in every project.
• builtins: false turns the built-in formatters off.
• timeoutMs limits each run. The default is 20 seconds.
• In a sandbox or on your own backend, give formatter() the same backend as workspaceTools().
• With workspaceTools({ workspace: { bind } }) before it, formatter() runs in the workspace of each thread. Leave out root and backend.

A formatter that fails, stops at the time limit, or is not installed does not fail the tool call. The file stays as the tool wrote it, and the plugin sends FormatFailed. A formatter that changes the file sends FormatterRewrote with { path, formatter }:

import { FormatFailed } from '@tanstack/ai-harness/plugins/coding'

export const formatAlerts = definePlugin({
  name: 'acme/format-alerts',
  setup: (ctx) => {
    ctx.on(FormatFailed, (failure) =>
      console.warn(`${failure.path}: ${failure.message}`),
    )
  },
})

Clients get the same events as a harness.plugin.event with the name tanstack/formatter:failed or tanstack/formatter:rewrote.

One approval covers the write and its formatter#

A formatter runs code from the project, like prettier.config.js. The model can change that code with an edit. So with permissions(), the rules decide the formatter as a part of the call that writes. The rule names the run formatter:prettier, formatter:biome, and so on.

The rules decide before the call runs, and the formatter runs after the write. The call never stops in the middle to ask.

• When the formatter asks, the call asks one time for the write and the formatter, also in acceptEdits mode. Answer that approval with resolve.
• A reject stops the call. Nothing is written, and the formatter does not run.
• Answer always once, and the formatter runs without a question in this project. The answer is tied to a hash of the formatter config files, like prettier.config.js and package.json. When they change, the next write asks again.
• A rule that denies the formatter keeps the write. The tool result says that the formatter did not run.
• A rule can allow a formatter: { tool: 'formatter:prettier', decision: 'allow' }. Without permissions(), the formatter runs without a question.

Formatters shows what each mode does.

Keep tool output small#

One tool result with a full log or a big JSON file fills the context of the model. boundToolOutput() cuts every tool result that is too long:

import { boundToolOutput } from '@tanstack/ai-harness/plugins/node'

export const bounded = defineHarness({
  name: 'acme/bounded-coder',
  adapter: openaiText('gpt-6.1-sol'),
  plugins: () => [
    workspaceTools({ root }),
    boundToolOutput({ dir: '.agent/tool-output' }),
  ],
})

• A result over 2000 lines or 50 KiB keeps its first lines and gets a note. Set other limits with maxLines and maxBytes.
• With dir, the full output goes to a file in dir, and the note gives the path. Files older than retentionDays (default 7) are removed.
• It cuts the result of every tool, MCP tools too, in the lead turn and in agent runs.
• An error stays an error. Images and other content parts do not change.

read_file and bash keep their output inside the default limits, so boundToolOutput() does not cut them again.

What you have now#

• The coding tools in a sandbox, with one option.
• Your project in a Docker container, with its uncommitted changes.
• A backend of your own for another place.
• Code that runs after each read and each write.
• Formatted files after each write, and tool results that fit the context.

Next: let the user undo the changes of a turn with snapshots.