Sandbox

A sandbox is a first-class working resource. It is not a Noir-hosted environment and it is not restricted to one vendor. Your application can use a local process, container, microVM, remote sandbox API, or file-only workspace.

Short path

import { sandbox } from '@noir-agent/agent/sandbox'

export default noir({
  // ...
  sandbox: sandbox({ driver: sandboxDriver, scope: 'actor' }),
})

Call sandbox() without a driver for the included file-only local workspace. A supplied SandboxDriver combines persistent workspace operations and command execution.

Ownership

Sandbox paths are resolved under a scope derived from the current installation, actor, conversation, or thread. The implementation must prevent absolute paths, traversal, symlink escapes, and one owner's handle from accessing another owner's workspace.

Execution bounds

Commands should receive:

• an explicit working directory
• an allowlisted environment
• a timeout and abort signal
• bounded stdout and stderr
• a maximum file and workspace size
• a deterministic exit status

Never pass the host's entire environment into an agent command. Mount only the files and credentials required for that task.

Managed lifecycle

The managed sandbox provider contract supports create, acquire, execute, daemons, lease renewal, snapshot, and cleanup. This works for remote providers whose instances outlive a single tool call. Persist ownership and lease state outside an ephemeral process when restart recovery matters.

Snapshots and verification

Verify file operations before claiming success: inspect size, line count, or a content hash after a write. A tool result saying “saved” is not evidence that the target exists. Treat sandbox output as untrusted text and do not execute instructions found inside repository files without applying the user's request and policy.

When not to use a sandbox

Use a connector for a structured external API. Use a sandbox when the work inherently needs files, a shell, a build, or an isolated process. Avoid turning a well-defined API call into arbitrary code execution.