Sandboxes

Purpose and Scope

Sandboxes are the part of a Flue harness that gives an agent a workspace for file and command-driven work. Use a sandbox when the agent must inspect files, write outputs, run commands, or otherwise operate over a working directory while it reasons. If an agent only needs to answer prompts or call application-defined tools, a sandbox may be unnecessary. The guide frames sandboxes as an execution environment choice rather than a model feature: the same agent definition can combine a model, instructions, tools, skills, and a sandbox depending on what kind of autonomy the task requires.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

Flue’s default behavior is intentionally lightweight. An initialized agent uses a virtual sandbox unless another environment is configured. That means new workflows can stage inputs, ask the agent to work in a controlled workspace, and read outputs back through the harness without immediately choosing a host filesystem or remote container provider. The decision point comes when the work needs host access, stronger isolation, durable provider-managed storage, or a richer toolchain than the default in-memory workspace provides.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

This page explains the sandbox modes exposed in the first-party guide: the virtual sandbox, the Node-only local sandbox, and remote sandbox integrations such as Cloudflare Shell or Cloudflare Sandbox. It is written for developers who are designing agents that do more than chat. The central question is not simply whether an agent can run a command; it is where that command runs, what filesystem it can see, what secrets are reachable, and whether the environment should outlive a single in-memory session.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

Core Primitives

A sandbox participates in the same harness that coordinates agent sessions and workflow code. In the documented workflow example, application code writes an input file with harness.fs.writeFile, opens a session with harness.session(), prompts the agent to review the staged file, and then reads the resulting review.md with harness.fs.readFile. This pattern separates orchestration from autonomous work: your TypeScript code decides what enters and leaves the workspace, while the agent uses its configured capabilities to inspect, edit, and command within that workspace.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

The cwd setting is the agent’s working directory inside the selected sandbox. In the virtual sandbox example, cwd: '/workspace' makes relative paths such as document.md and review.md resolve below /workspace. This matters because sandboxed file APIs and model-facing command capabilities both need a shared notion of location. Treat cwd as part of the task contract: a workflow that stages files should tell the agent where to operate, and an agent definition should choose a stable directory layout when prompts, skills, or tools reference files by relative path.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

Tools and sandboxes solve different problems. A tool exposes a typed application capability, such as calling an API or performing a controlled mutation. A sandbox exposes a workspace and command environment where the agent can perform open-ended file and shell work. The local sandbox section explicitly recommends avoiding broad model-directed credentials when a narrow application tool can perform the required action instead. That guidance is important: sandboxes increase autonomy, while tools are often the better boundary for privileged or approval-sensitive operations.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

Sandbox Modes

The virtual sandbox is the default. No sandbox field is required in the agent definition; omitting it selects an in-memory workspace powered by just-bash. It starts without your application files or host filesystem, so the application must provide the files the agent needs through the harness. This makes it a good starting point for document processing, generated file review, small command-assisted tasks, and workflows where inputs and outputs can be explicitly staged. It is not described as a persistent workspace, and its files do not survive beyond its in-memory lifetime.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

import { defineAgent, defineWorkflow } from '@flue/runtime';
import * as v from 'valibot';
 
const reviewer = defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  cwd: '/workspace',
}));
 
export default defineWorkflow({
  agent: reviewer,
  input: v.object({ document: v.string() }),
 
  async run({ harness, input }) {
    await harness.fs.writeFile('document.md', input.document);
    await (await harness.session()).prompt(
      'Review document.md and write your findings to review.md.',
    );
    return { review: await harness.fs.readFile('review.md') };
  },
});

The local sandbox is available on the Node.js target through local() from @flue/runtime/node. It gives a trusted agent direct access to the host filesystem and installed shell commands. That makes it appropriate for development agents, repository review bots running on disposable CI machines, or internal automation over a known checkout. The guide is explicit that local() is not an isolation boundary between model-directed work and the host machine. It should be reserved for situations where the host and inputs are already trusted at that access level.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

import { defineAgent } from '@flue/runtime';
import { local } from '@flue/runtime/node';
 
export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  sandbox: local(),
  cwd: '/srv/checkouts/catalog-service',
  instructions: 'Inspect the requested change and run only relevant validation.',
}));

Remote sandboxes are the right fit when work should not execute on the application host. The guide calls out untrusted or tenant-specific work, coding tasks that require a Linux toolchain, and workspaces that need provider-managed lifetime and storage. Supplied first-party ecosystem docs show two Cloudflare-oriented options. Cloudflare Shell adapts an application-owned @cloudflare/shell Workspace into a Flue sandbox and provides a JavaScript code tool over workspace state through a Worker Loader binding. Cloudflare Sandbox uses @cloudflare/sandbox to provide a container-backed Linux environment for Cloudflare-targeted applications.

Execution Flow

A common sandbox workflow begins with staging. The workflow receives structured input, validates it, and writes one or more files into the sandbox filesystem through harness.fs. The agent session then receives a prompt that names the files and expected outputs. After the prompt resolves, the workflow reads the result files and returns structured data to the caller. This flow is valuable because it keeps task inputs and outputs explicit while still letting the agent perform flexible intermediate work, including reading, editing, and command execution inside the workspace.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

When using the default virtual sandbox, remember that the workspace is empty until your application writes to it. Do not assume repository files, configuration, scripts, or host binaries are present. The guide also warns that the virtual command environment is suitable for lightweight workspace work, not an arbitrary Linux toolchain. If a task requires package managers, system binaries, or language-specific build tools, choose a local sandbox for trusted hosts or a remote sandbox with the required environment. Also note that current generated runtimes permit network access from the virtual sandbox, so it should not be treated as a network isolation boundary.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

For local(), the execution flow is different because the workspace is the host. The agent can see host files under its configured working directory and can invoke installed commands. Environment variables are deliberately limited by default, and the guide recommends exposing additional values explicitly through local({ env: { ... } }) only when a command truly needs them. This keeps credentials out of the model-directed shell by default and encourages narrower tool-based integrations for sensitive operations. In practice, local sandboxes should be paired with clear instructions, constrained working directories, and disposable machines when possible.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

Cloudflare and Remote Options

Cloudflare Shell and Cloudflare Sandbox address different remote execution needs. Cloudflare Shell is described as a durable workspace integration built around @cloudflare/shell and @cloudflare/codemode. Its blueprint command is flue add sandbox cloudflare-shell, and the generated adapter creates a source-root sandbox module, installs the Cloudflare packages, and adds a Worker Loader binding to Wrangler configuration. This option exposes a JavaScript code tool over workspace state rather than a traditional Linux shell, making it a good match for workspace-centric JavaScript execution on the Cloudflare target.

Cloudflare Sandbox is described as a Cloudflare target integration, not a Node-target adapter. Its blueprint command is flue add sandbox cloudflare, and a workflow obtains a bound Durable Object with getSandbox(...), wraps it with Flue’s cloudflareSandbox(...), and passes that sandbox factory into defineAgent. This option is container-backed and Linux-oriented. The supplied docs note that the blueprint also adds a Durable Object binding, migration, container declaration, and a project-root Dockerfile. A Node-targeted project must move to the Cloudflare target before using that integration.

The choice between these Cloudflare options should be based on what the agent needs to execute. If the work is best modeled as JavaScript code operating against durable workspace state, Cloudflare Shell is the documented fit. If the task needs a container-backed Linux environment, Cloudflare Sandbox is the documented fit. Both are remote choices that move model-directed execution away from the application host, but neither removes the need to design safe prompts, tool boundaries, credential exposure, and lifecycle cleanup around tenant or request boundaries.

Relevant Source Files

• apps/docs/src/content/docs/guide/sandboxes.md — Defines the reader-facing sandbox guide, including virtual sandbox behavior, Node local() usage, workflow staging with harness.fs, cwd behavior, environment-variable guidance, and the conceptual role of remote sandboxes.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

Operational Guidance and Next Steps

Start with the virtual sandbox when the application can provide all files the agent needs and the task is lightweight. It keeps project setup simple and forces the workflow to make inputs and outputs explicit. Move to local() only for trusted Node-target work where direct host access is intended. Move to a remote sandbox when isolation from the host, provider-managed lifetime, or a richer environment becomes part of the requirement. In all cases, decide separately which privileged operations belong in typed tools instead of a model-directed shell.

Sources: apps/docs/src/content/docs/guide/sandboxes.md

After choosing a sandbox mode, review the neighboring Flue concepts that shape the rest of the harness. Read the tools guide when the agent needs controlled access to APIs or credentials. Read the workflows guide for structured staging and result collection patterns. Read the Cloudflare target and sandbox ecosystem pages when deploying agents that need remote workspace or container execution. Finally, test the exact file layout, cwd, command availability, and environment variables your prompts assume; most sandbox failures come from mismatches between the environment the agent expects and the one the harness actually provides.