Sandboxes Agents

Purpose and Scope

A Flue agent is best understood as a language model running inside a programmable harness. The model supplies reasoning, but the harness supplies continuity, filesystem access, command execution, tools, skills, routing, and the runtime boundary that lets the agent perform useful work. This page explains that concept through the sandbox layer: the part of the harness that gives an agent a workspace where it can read files, write files, and run commands while pursuing a task. It is intended for developers deciding how much autonomy to give an agent and where that autonomy should execute.

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

The sandbox is not an optional implementation detail once an agent needs to act on files or run shell-driven work. The sandboxes guide distinguishes agents that only respond to prompts or call application-defined tools from agents that need a workspace for command-driven activity. That distinction is central to designing a safe Flue agent: prompts and tools are controlled interfaces, while a sandbox gives the model a broader operational surface. Choosing the right sandbox therefore shapes what the agent can inspect, what it can modify, which commands it can run, and what isolation assumptions your application can make.

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

Relevant Source Files

apps/docs/src/content/docs/guide/sandboxes.md — Defines the user-facing sandbox model for Flue agents, including the default virtual sandbox, Node local sandbox behavior, remote sandbox guidance, filesystem examples, working-directory semantics, and safety notes about persistence, environment variables, host access, and network isolation.

Core Primitives

The core primitive is the agent harness. In Flue, an agent definition selects a model and can add instructions, tools, skills, a working directory, and a sandbox. Instructions tell the agent what role to play and what constraints to follow. Tools expose typed application operations, which are preferable when the agent needs a narrow, auditable way to call an API or make a controlled change. Skills package reusable guidance or procedures. The sandbox is different: it gives the agent a workspace and command surface, so the model can inspect and transform artifacts rather than only request application operations.

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

The virtual sandbox is the default primitive for workspace-backed agents. If an agent is initialized without an explicit sandbox field, Flue places it in a lightweight in-memory workspace powered by just-bash. The guide presents this as the right starting point when the application can provide the files the agent needs. That default matters because it lets developers begin with an agent that can use filesystem and command capabilities without immediately granting access to the host filesystem. It also keeps the agent’s workspace lifecycle separate from project files unless the application intentionally stages content into it.

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

A working directory is the coordinate system for sandbox work. In the guide’s example, the agent sets cwd: '/workspace', then the workflow writes document.md, prompts the agent to create review.md, and reads the result back. Relative paths resolve below the configured working directory, so the application and the agent share a predictable workspace contract. This pattern is especially useful for durable agent or workflow designs because the application can stage inputs, let the agent work through a session, and retrieve outputs as files rather than trying to encode every intermediate step as structured data.

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

System-to-Code Mapping

The sandbox guide maps directly to the public authoring flow used by Flue projects. An agent can be declared with defineAgent, given a model such as anthropic/claude-sonnet-4-6, and configured with a cwd. A workflow can then compose that agent with defineWorkflow, validate input with valibot, and use the harness object to write files, open a session, prompt the agent, and read output files. The important design point is that application code remains responsible for staging trusted inputs and collecting results, while the agent is responsible for doing the open-ended reasoning and workspace manipulation inside the configured environment.

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

import { defineAgent, defineWorkflow } from '@flue/runtime';
 
const reviewer = defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  cwd: '/workspace',
}));
 
export default defineWorkflow({
  agent: reviewer,
  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') };
  },
});

This example also shows how sessions and files fit together. The session is the continuing interaction channel with the agent; the filesystem is the durable-looking workspace interface used during the run; and the prompt is the task instruction that tells the agent what artifact to produce. The application does not need to predefine each edit the agent will make. Instead, it defines the workspace boundary and the expected input/output files. That is the harness pattern in miniature: give the model enough environment to solve the task, while keeping ownership of the surrounding application flow in TypeScript.

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

Sandbox Choices and Safety Boundaries

The virtual sandbox is convenient, but it is intentionally limited. The guide states that it starts without application files or host filesystem access, and its files do not persist beyond its in-memory lifetime. Its command environment is suitable for lightweight workspace work, not an arbitrary Linux toolchain. Those properties make it a good default for document review, generated artifacts, small transformations, or tasks where the application can inject all needed files. They also prevent a common mistake: assuming the default workspace is a mirror of the repository or a persistent job volume.

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

The virtual sandbox should not be treated as a network isolation boundary. The guide explicitly notes that current generated runtimes permit network access from the virtual sandbox. That means developers should still design agents as network-capable actors unless another layer enforces network restrictions. If a task involves secrets, tenant data, or untrusted prompts, do not rely on the virtual sandbox alone for isolation. Prefer narrow tools for privileged operations, and choose a remote or provider-managed sandbox when the work requires a stronger separation from the application host.

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

On the Node.js target, the local() sandbox is the opposite tradeoff: it allows a trusted agent to operate directly on the host filesystem and shell. The guide positions this for trusted development tools or disposable CI runners working against an existing checkout. That is powerful for repository review, validation, migrations, and code-modifying agents because installed commands and real files are reachable. It is also risky by design. local() does not isolate model-directed work from the host machine, so it should only be used when the host and the input are already trusted for that level of access.

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

Environment variables are another part of the safety boundary. The local sandbox deliberately limits host environment variables by default, and the guide recommends exposing additional values explicitly through local({ env: { ... } }) only when a command requires them. This keeps broad credentials out of the model-directed shell. The guide also points developers back to application tools for sensitive actions: when a narrow tool can perform the required operation, it is usually safer than handing the agent an environment variable and a shell command that can use it in arbitrary ways.

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

Remote Sandboxes and Routing Context

Remote sandboxes are the choice when agent work should not run on the application host. The guide names untrusted or tenant-specific tasks, coding work that requires a Linux toolchain, and workspaces that need provider-managed lifetime and storage as examples. Conceptually, a remote sandbox lets the Flue agent remain the same programmable resource while changing the execution environment behind its workspace capabilities. The model, instructions, tools, skills, and route exposure can stay part of the agent design, while the sandbox integration supplies the isolated environment appropriate for the task.

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

Routing is how an agent becomes reachable from users or systems, but routing should not be confused with sandboxing. First-party agent docs describe route handlers that can expose an agent over HTTP, while the sandbox guide explains where the agent’s workspace actions execute. A routed repository reviewer using local() has a very different trust profile from a routed document reviewer using the virtual sandbox. When designing a public route, decide the ingress policy, authentication, and request shape separately from the sandbox choice, then verify that the chosen sandbox is safe for the class of callers reaching that route.

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

Implementation Details

A practical authoring rule is to start with the least powerful harness that still solves the task. If the application can stage files and collect outputs, omit the sandbox field and use the virtual sandbox. If the task needs a real checkout and installed host commands, use local() only in trusted Node environments. If the task is untrusted, tenant-specific, toolchain-heavy, or should have its own lifecycle and storage, use a remote sandbox integration. This progression keeps the agent abstraction stable while changing the operational boundary to match the risk and capability needs.

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

The relationship between tools and sandboxes is especially important. Tools are application-defined capabilities with typed inputs and controlled behavior; sandboxes are broader execution environments where the agent can manipulate files and run commands. A strong Flue design often uses both: tools for privileged, business-specific actions, and a sandbox for exploratory or artifact-oriented work. For example, an agent might use a sandbox to inspect generated files and run validation, but call a tool to create a GitHub comment, update a ticket, or read sensitive data through an audited path.

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

Next Steps

When building an agent, define the model, instructions, tools, skills, and route first, then decide which sandbox makes those capabilities safe and useful. Use the virtual sandbox for staged file workflows, local() for trusted Node host access, and remote sandboxes for isolated or provider-managed execution. After choosing the sandbox, document the working directory, input files, expected output files, and any explicitly exposed environment variables so future maintainers understand the harness contract. Then read the related pages on building agents, tools, workflows, routing, durable execution, and the sandbox API for the corresponding reference details.

Ask a question...