Sandbox

Purpose and Scope

The sandbox is the isolated execution environment that eve gives to each agent. It is a bash-capable filesystem rooted at /workspace, and it is intentionally separate from the application runtime. That separation is the core safety and operability boundary: the agent can run commands, create scripts, inspect files, and write artifacts without directly mutating the process that hosts your web app or agent server. Every eve agent has exactly one sandbox, so developers should treat it as the agent’s working area rather than as an optional plugin or a per-tool scratch directory.

Sources: docs/sandbox.mdx

A working sandbox exists by default, which means most agents do not need a sandbox file or special setup before they can use shell and file capabilities. The default model-facing tools already know how to target the sandbox, and authored runtime code can request a handle when it needs programmatic access. Override the default only when the application needs seeded files, setup work, a selected backend, or a stricter network posture. The docs are explicit that the default sandbox is not a replacement for application-specific controls such as credential handling, retention, deletion, or network policy.

Sources: docs/sandbox.mdx

This page is for developers deciding how to let an agent analyze data, run generated code, manipulate files, or call external systems without confusing those actions with application-side execution. It covers the public mental model, the built-in tool surface, the authored-code handle available through runtime context, and the practical safeguards to consider before exposing shell, file, or network behavior to real users. It does not require understanding eve’s internal workflow implementation; the sandbox is presented as a runtime primitive available inside normal agent execution.

Sources: docs/sandbox.mdx

Relevant Source Files

• docs/sandbox.mdx — Defines the sandbox concept, the default built-in shell and file tools, the /workspace path model, the runtime ctx.getSandbox() access pattern, and the public sandbox handle methods shown in the docs.

Core Primitives

The first primitive is the workspace itself. All built-in shell and file tools operate with /workspace as their working directory, so relative paths should be understood as relative to that root. The docs emphasize that /workspace is one namespace across backends: a path such as /workspace/foo names the same logical file whether the sandbox backend is local or Vercel. That consistent namespace lets tools, generated scripts, and authored runtime code share paths without needing separate path conventions for development and production.

Sources: docs/sandbox.mdx

The second primitive is the model-visible tool family. The built-in bash tool runs shell commands in the sandbox, while read_file and write_file read and write under /workspace. The glob tool finds files by pattern, and grep searches file contents. These tools are available without authoring custom code, which is why a new eve agent can already inspect files, create analysis scripts, and run commands. They should still be treated as powerful capabilities, especially when prompts can influence commands or file contents.

Sources: docs/sandbox.mdx

The third primitive is the sandbox handle available to authored runtime functions. Inside a tool, step, or model callback, code can call ctx.getSandbox() to get a live handle. That function takes no arguments, is asynchronous, and only works during authored runtime execution. This distinction matters because the handle belongs to the agent turn, not to arbitrary build-time or configuration code. Use it when deterministic TypeScript code needs to prepare files, run a command, read an output, or change sandbox behavior in a controlled way.

Sources: docs/sandbox.mdx

Built-in Tools and Runtime Handle

The built-in tools are useful when the model should decide which files to inspect or which command to run. The runtime handle is better when application code should own the sequence. For example, a custom analysis tool can accept a script string, write that script to a known file, run a fixed command, and return only the command output. That approach still uses the sandbox, but it reduces ambiguity because the TypeScript tool controls the path, command shape, and result mapping instead of leaving all details to a model-generated shell invocation.

Sources: docs/sandbox.mdx

import { defineTool } from "eve/tools";
import { z } from "zod";
 
export default defineTool({
  description: "Run a Python analysis script and return its output.",
  inputSchema: z.object({ script: z.string() }),
  async execute({ script }, ctx) {
    const sandbox = await ctx.getSandbox();
    await sandbox.writeTextFile({ path: "analysis/run.py", content: script });
    const result = await sandbox.run({ command: "python analysis/run.py" });
    return { stdout: result.stdout };
  },
});

The example demonstrates the intended control boundary. The model can call a typed tool with a validated input, but the tool implementation decides where the script is stored and what command is executed. The sandbox receives the filesystem and process operations, while the application runtime remains separate. This pattern is especially useful for analytical agents that need to create temporary scripts, execute them, and return summarized output. It also gives developers a clear place to add validation, logging, approvals, or network restrictions around the sandbox action.

Sources: docs/sandbox.mdx

Path Model and File Operations

Path handling is deliberately simple. Relative paths resolve from /workspace, and absolute paths pass through untouched. When authored code needs to interpolate a file path into a generated command, sandbox.resolvePath("repo/build.py") anchors the relative path to an absolute /workspace/repo/build.py form. This is useful because shell commands are often assembled from smaller values, and ambiguity around the current directory can create bugs or unsafe behavior. Prefer resolving paths deliberately when a command string depends on a file produced by prior sandbox operations.

Sources: docs/sandbox.mdx

The handle includes text, binary, and streaming file operations. readTextFile and writeTextFile support UTF-8 text by default, with specified encodings available; the read method also supports one-based line ranges. readBinaryFile and writeBinaryFile handle raw bytes such as images or archives, while readFile and writeFile stream bytes in and out. These method families let a tool match the data shape it is actually working with instead of forcing every artifact through shell commands or text strings.

Sources: docs/sandbox.mdx

Deletion is explicit through removePath({ path, force, recursive }). The force option ignores missing paths, and recursive removes non-empty directories. That makes cleanup code easier to write, but it also means deletion behavior should be deliberate. If a tool writes generated files into a predictable subdirectory such as analysis/, cleanup can target that subdirectory instead of broad workspace paths. The same principle applies to writes: choose narrow, predictable paths so the agent’s artifacts are understandable during debugging and easier to remove when a run is complete.

Sources: docs/sandbox.mdx

Execution Isolation and Lifecycle Considerations

Sandbox work happens inside the agent’s execution path, but the docs distinguish the sandbox runtime from the app runtime. The agent can run shell commands and read or write files without touching the app runtime directly. That separation helps keep generated scripts, temporary files, and command output away from the code serving routes or rendering the frontend. It does not mean commands are harmless. A command can still consume resources, produce sensitive artifacts, or attempt network access, so tool authors should decide which operations belong in model-visible tools and which should be wrapped in typed application code.

Sources: docs/sandbox.mdx

Long-running processes are represented separately from single commands. Use run for one command that should block until it exits, and use spawn when the sandbox needs to launch something like a server or watcher. The distinction helps readers model lifecycle expectations: a blocking analysis command should produce output and finish, while a spawned process needs a process handle and ongoing management. The docs name SandboxProcess as the returned handle type for spawned work, which signals that lifecycle is part of the public sandbox abstraction rather than an accidental shell detail.

Sources: docs/sandbox.mdx

The sandbox also participates in durable agent work because authored runtime functions can use it from tools, steps, and model callbacks. Developers should therefore write sandbox interactions as part of a turn’s controlled execution rather than as global process state. Store inputs and outputs under clear workspace paths, return structured results from tools, and avoid relying on hidden side effects outside the workspace. This keeps sandbox behavior understandable when an agent turn includes multiple tool calls, generated files, command output, and later reasoning over the files it created.

Sources: docs/sandbox.mdx

Network Policy and Safety Practices

The sandbox page explicitly warns that the default sandbox is not a substitute for network policy, credentials, retention, deletion, or other controls required by an application. Treat that warning as a design requirement. If an agent can run shell commands or generated scripts, decide whether it may reach the public internet, internal services, package registries, or tenant-specific resources. The handle exposes setNetworkPolicy(policy) for changing egress policy mid-turn when the backend supports it, so network behavior can be part of runtime control rather than only a static deployment assumption.

Sources: docs/sandbox.mdx

File and shell tools should be paired with least-privilege design. Prefer narrow custom tools for sensitive workflows: validate inputs, write to a controlled subdirectory, run a specific command, and return a constrained result. Let the model use generic bash, grep, and file tools when exploratory work is appropriate, but do not confuse convenience with a security boundary. Credentials should be handled according to the application’s deployment and secret-management model, not copied into generated files by default. Retention and deletion should be planned for artifacts that may contain user data or analysis outputs.

Sources: docs/sandbox.mdx

The most practical safeguard is to make the workspace legible. Use predictable directories such as analysis/, tmp/, or a task-specific folder, resolve paths before interpolating them into commands, and remove artifacts when they are no longer needed. When a tool returns command output, decide whether to include only stdout, include stderr, or map results into a domain-specific object. These choices make agent behavior easier to audit and reduce the chance that an accidental file path, verbose log, or generated command leaks more context than the user task requires.

Sources: docs/sandbox.mdx

Next Steps

Start with the default sandbox and avoid configuration until a concrete requirement appears. If the agent only needs ordinary shell and file access, the built-in tools and /workspace convention are enough. When a workflow needs repeatable behavior, wrap sandbox operations in a typed tool that uses ctx.getSandbox(), writes files to known paths, and returns a structured result. When the workflow touches external systems, add explicit network, credential, retention, and deletion decisions before shipping. For broader context, read the pages on tools and approvals, execution durability, deployment, and project layout.

Sources: docs/sandbox.mdx