Eve

Eve is an open-source framework from Vercel for durable backend agents; an agent is a directory, and each framework tool occupies an agent/tools/<name>.ts slot that the host can replace, wrap, or disable. Eve is not a coding agent: its file family is three default tools, bash, read_file, and write_file, plus opt-in glob and grep, with no edit tool. Every tool runs in the app runtime and proxies into a per-session sandbox through a SandboxSession, so path, error, and shell behaviour depend on the backend. This page describes the default tool set over the just-bash backend, the dependency-free fallback at the end of the defaultSandbox() chain, and names the Docker and Vercel Sandbox backends where their read, write, or shell paths differ.

Source

Tool inventory

Each default occupies an agent/tools/<name>.ts slot. A file at that path replaces the default; export default disableTool() removes it; spreading the exported definition into defineTool() wraps it. defaultTools: false in agent/agent.ts drops every optional default except connection_search, and files under agent/tools/ stay available. glob and grep are published at eve/tools/glob and eve/tools/grep and are never registered by default. Not on this page: the self-modification extension's edit_file, which edits the agent's own source through the app runtime rather than the sandbox, and any MCP or connection tools.

Read

Signature

read_file({ filePath: string, offset?: number, limit?: number })

filePath must be absolute or begin with $HOME/. offset is one-based; the schema requires an integer of at least 1 and the executor defaults it to 1. limit is a line count, integer, at least 1, default 2000, with no maximum. The input schema is z.strictObject, so an unknown key fails validation. The output schema is content, path, totalLines, truncated, and an optional nextOffset.

Description

read_file: 784 characters, 784 bytes, 11 lines, approximately 182 tokens.

read_file (784 characters)

Read a file from the local filesystem. If the path does not exist, an error is returned.

Usage:
- The filePath parameter should be an absolute path or begin with $HOME/.
- By default, this tool returns up to 2000 lines from the start of the file.
- The offset parameter is the line number to start from (1-indexed).
- To read later sections, call this tool again with a larger offset.
- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents "foo\n", you will receive "1: foo\n".
- Any line longer than 2000 characters is truncated.
- Call this tool in parallel when you know there are multiple files you want to read.
- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.

Path handling

resolveSandboxModelPath in shared/skill-paths.ts handles one prefix. A path equal to $HOME or starting with $HOME/ has that prefix replaced by the sandbox home, found by running printf '%s\n' "$HOME" through sandbox.run. The answer is cached in a WeakMap keyed by the session object, and the tool context hands each call a fresh abort-bound wrapper, so the probe runs again for every tool call that uses a $HOME path. When the probe fails or returns a value that is empty, relative, or contains a control character, only $HOME/.agents/skills paths are rewritten, to /workspace/skills; other $HOME paths pass through unchanged and then fail the absolute check. No other shell syntax is evaluated. The result must start with /:

filePath must be an absolute path. Received: "<path>". Use an absolute path such as /workspace/foo.ts or a path beginning with $HOME/.

The read goes to the backend with the resolved path. posix.normalize then collapses dot segments for the stamp key and for the path field in the result. There is no ~ expansion, no file:// handling, no @ stripping, no realpath, no sibling or unicode recovery, and no fallback to the working directory. A relative path is rejected even though the session's own resolvePath would anchor it at /workspace.

Symlinks: on just-bash the ReadWriteFs is built with allowSymlinks: true, so links are followed. On Docker cat follows them. On Vercel Sandbox: Unverified.

Permissions

Binary and conversion

Limits

totalLines counts a trailing newline as the end of the last line, not as an extra line. A file with limit lines left after offset is not truncated; one fewer is.

Output

{
  "content": "1: import { x } from \"./x\"\n2: export const y = x",
  "path": "/workspace/src/y.ts",
  "totalLines": 2,
  "truncated": false
}

The example is reconstructed from the format code. The JSON spacing the provider receives was not observed. An empty file returns content: "", totalLines: 0, truncated: false.

Notable

• Read stamp: every read that passes validation stores a SHA-256 of the full content and its UTF-8 byte length in durable session state under eve.readFile, keyed by the normalised path. A read that throws stores nothing.
• Repeat-read guard: None. Content injection after the read: None. Redaction: None.
• Cancellation: the tool context binds the AI SDK abort signal to every sandbox call through bindSandboxAbortSignal. The Docker read passes it to docker exec; the just-bash and Vercel read primitives ignore it.
• Tool results, including the numbered content, persist in durable workflow state as JSON, so reads replay after a restart.
• Host knobs on this family: agent/tools/read_file.ts override or wrapper, disableTool(), defaultTools: false, approval on a wrapped definition; the sandbox backend factory (defaultSandbox(), justbash(), docker(), vercel(), microsandbox()); and on justbash() the filesystem factory option, which receives defaultFilesystem and the justBash module and can return any IFileSystem, plus customCommands that run in the host process.

Edit

Signature

Not applicable. Eve has no targeted edit or patch tool; the only mutation tool is write_file, which replaces the whole file, and the model deletes or renames through bash.

write_file({ filePath: string, content: string })

Description

write_file: 627 characters, 627 bytes, 8 lines, approximately 125 tokens.

write_file (627 characters)

Writes a file to the local filesystem.

Usage:
- This tool will overwrite the existing file if there is one at the provided path.
- If this is an existing file, you MUST use the read_file tool first to read the file's contents. This tool will fail if you did not read the file first.
- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.

Whole-file write

executeWriteFileOnSandbox resolves the path as read_file does, then reads the current file in full through readTextFile, because the stale check hashes content and the session has no exists() primitive; the source comment records this as a known cost. A missing file is written at once with no prior read required. An existing file goes through the checks below and is then written with writeTextFile, which encodes UTF-8 and streams the bytes to the backend.

Backend write paths: just-bash calls filesystem.mkdir(dirname, { recursive: true }) and then filesystem.writeFile; Docker runs mkdir -p <dir> && cat > <path> through docker exec -i with the bytes on stdin; Vercel Sandbox calls sandbox.writeFiles after resolveVercelWritePath, and parent creation there is Unverified. The write is direct on every surveyed backend: no temporary file and rename, no backup, and no read-back. BOM and line endings are written as supplied. Mode preservation: Not surveyed. Because readTextFile decodes in fatal mode, write_file over an existing file with invalid UTF-8 throws the decoder error before any check.

Matching

Not applicable. There is no string-replace tool and no fallback cascade.

Multi-file patch

Not applicable. There is no patch grammar and no multi-file tool.

Verification and mutation state

Output

{ "existed": true, "path": "/workspace/notes.md" }

The example is reconstructed from the output schema.

Notable

• No notebook editor, no undo, no checkpoint tool for the model. The session has removePath for authored code; the model has no delete tool.
• The docs suggest wrapping write_file to reject paths outside /workspace/, which confirms that the framework applies no path restriction of its own.
• Host knobs on this family: agent/tools/write_file.ts override or wrapper with its own execute and approval, disableTool(), defaultTools: false, and the sandbox backend factory. The stamp logic lives in the executor, so a wrapper that calls writeFile.execute keeps it and one that writes through ctx.getSandbox() directly bypasses it.

Shell

Signature

bash({ command: string })

One command string. There is no timeout, cwd, env, background, or permission parameter. The output schema is exitCode, stderr, stdout, and truncated.

Description

bash: 60 characters, 60 bytes, 1 line, approximately 10 tokens.

bash (60 characters)

Execute a shell command in the shared workspace environment.

Working directory and environment

executeBashOnSandbox calls sandbox.run({ command }) with no other option, although SandboxSpawnOptions accepts workingDirectory and env. run in buildSandboxSession is a wrapper over the backend spawn: it collects stdout and stderr to strings with a non-fatal TextDecoder, awaits wait(), and returns exitCode, stderr, and stdout.

The working directory is /workspace (WORKSPACE_ROOT) on every backend: just-bash creates its Sandbox with cwd: "/workspace"; Docker passes -w /workspace to docker exec; Vercel Sandbox passes cwd: "/workspace" to runCommand.

Shell and environment by backend:

Tool execute functions run in the app runtime with process.env and secrets; the model's commands run in the sandbox with no path back, which is the framework's stated security split.

Process lifecycle

Output limits

Sandbox

setNetworkPolicy is a hook for authored code such as onSession and tool wrappers; the model has no tool that calls it. The SandboxNetworkPolicy type is the @vercel/sandbox NetworkPolicy.

Approval

None on the provided tools. defineTool accepts approval and approvalKey; the always, never, and once helpers in eve/tools/approval cover the common cases, and a wrapper in agent/tools/bash.ts can set them. No command parser, allowlist, or pattern table exists. The approval prompt and denial text: Not surveyed.

Notable

• A non-zero exit is a plain result with exitCode set. The model has to read the field.
• No PTY, no interactive input, no streaming to the model.
• just-bash has no separate bash executable; eval re-parses the single string argument because the object form of runCommand is the only form that supports detached.
• Host knobs on this family: agent/tools/bash.ts override or wrapper with approval, disableTool(), defaultTools: false; the backend factory and its options (justbash({ filesystem, customCommands, autoInstall }), docker(), vercel(), microsandbox()); and setNetworkPolicy from authored code.

Search and listing

Tools

A probe runs command -v rg and one rg search once and caches the answer by session.id, which survives the per-call wrapper; a probe that throws is retried on the next call. Exit codes 0 and 1 are success; exit 1 with non-empty stderr, or any other code, throws. Truncation runs in JavaScript rather than through | head, so a missing binary is not masked by a pipeline exit code. glob returns newline-joined normalised paths, or No files found, and appends a blank line and (Results truncated: showing first <n> results out of more. Use a more specific path or pattern to narrow results.) when cut. grep returns the raw <path>:<line>:<text> rows, counts rows that match ^.+:\d+: as matches, returns No matches found on empty output, and appends a bracketed notice when cut: [Match limit reached (<limit>). Use a larger limit or more specific pattern.], [Output truncated due to size. Use a more specific path or pattern.], or both joined by a space. Because limit is per file, total grep output is bounded only by the byte cap. On just-bash there is no rg, and find and grep are the interpreter's built-in implementations. Listing goes through bash with ls.

Description

glob (opt-in): 249 characters, 249 bytes, 6 lines, approximately 53 tokens. grep (opt-in): 452 characters, 452 bytes, 9 lines, approximately 102 tokens.

glob (249 characters, opt-in)

Fast file pattern matching tool that works with any codebase size.

Usage:
- Supports glob patterns like "**/*.js" or "src/**/*.ts".
- Returns matching file paths.
- Call this tool in parallel when you know there are multiple patterns to search for.

grep (452 characters, opt-in)

Fast content search tool that works with any codebase size.

Usage:
- Searches file contents using regular expressions.
- Supports full regex syntax (e.g. "log.*Error", "function\s+\w+").
- Filter files by pattern with the glob parameter (e.g. "*.js", "*.{ts,tsx}").
- Returns matching lines with file paths and line numbers.
- Call this tool in parallel when you have multiple independent searches.
- Any line longer than 2000 characters is truncated.

Errors

The provided executors throw plain Error objects with no code. The harness does not catch them; the AI SDK records a tool-error part, and createToolResultMessagePartFromToolError in harness/action-result-helpers.ts places the message in a tool-result part with output type error-text so the model sees the text. A semantic-errors classifier reads the same errors for telemetry without changing the text. The exact bytes the AI SDK sends for the part were not observed.