Giving agents a sandbox

Some agent tasks need more than an API call. A debugging agent may need to inspect a repository. A reporting agent may need Python and a filesystem. A coding agent may need to start a development server and check the result in a browser.

Giving a model direct access to the host process is the shortest path to those capabilities—and the wrong default. @anvia/sandbox places command execution and file operations inside a controlled Docker workspace instead.

A session becomes a tool boundary

The application creates the Sandbox and owns its policy. The agent only receives the tools derived from one live session:

import { AgentBuilder } from "@anvia/core"
import {
  DockerSandbox,
  createSandboxTools,
} from "@anvia/sandbox"

const sandbox = DockerSandbox.node({
  network: false,
})

const session = await sandbox.createSession({
  id: "support-debug",
})

const tools = createSandboxTools(session, {
  exec: {
    maxTimeoutMs: 30_000,
  },
})

const agent = new AgentBuilder("debugger", model)
  .instructions("Inspect files only inside the sandbox workspace.")
  .tools(tools)
  .defaultMaxTurns(8)
  .build()

The session is the capability boundary. It determines the workspace, image, network mode, process limits, published ports, file limits, and lifecycle. Prompt text cannot widen those constraints.

Execution needs more than isolation

Docker provides a useful process and filesystem boundary, but a production-quality tool contract also has to bound the work inside it.

Sandbox command tools can restrict allowed and blocked executables, maximum timeouts, output size, and whether long-running process controls are exposed. File tools normalize paths to the workspace and enforce read and write limits. Large text files use bounded line pagination with continuation metadata instead of flooding the model context.

The application can place Anvia approval policies around commands or file writes that need human review. Observability hooks record command lifecycle and failures without changing the model-facing tool definition.

Isolation, policy, approval, and observability solve different parts of the problem. Sandbox keeps them composable rather than treating the container as a complete security policy by itself.

Persistent workspaces and explicit cleanup

An ephemeral session is useful for a single task. Longer workflows need a workspace that survives several agent runs, streaming commands, and application requests.

Sandbox sessions can persist for that lifecycle while the application retains cleanup control. Destroying a session removes its workspace, managed processes, and published ports together. Stopping Studio does not destroy it, and a model cannot silently take ownership of its lifetime.

This is especially important for failures. Cleanup should not depend on the model reaching the final tool call it was expected to make.

Building the environment the task needs

The create-image CLI generates local Docker images from a selected runtime and feature set. The documented presets cover Node.js, Python, and Deno, and the generated build context lives under .anvia/sandbox-images so teams can review and commit it.

The image becomes reviewable infrastructure instead of an improvised install sequence inside every run. Build required dependencies into the image so their versions remain explicit and a session does not need network access merely to install packages.

Live previews without public container ports

Sandbox can start and manage a long-running process, wait for a container port, and publish it to a random loopback-only host port. The consuming application then proxies that target through its own authenticated route or preview domain.

The internal host address is never meant to be sent directly to a remote browser. Product authentication, HTTP and WebSocket proxying, URL policy, and preview lifetime remain application responsibilities.

Studio can look, but not take over

Tools created by createSandboxTools(...) carry runtime metadata that lets @anvia/studio discover their session. Studio can then show files, downloads, managed processes, ports, and logs in a read-only Sandbox inspector.

It does not scan arbitrary Docker containers, write files, stop processes, or destroy the session. Discovery is limited to sessions already attached to configured agents. The application remains the owner on both sides of the integration.

Read the Sandbox package documentation, the sandbox execution guide, and the Sandbox changelog.