Filesystem backend with unrestricted local shell command execution.
This backend extends FilesystemBackend to add shell command execution capabilities. Commands are executed directly on the host system without any sandboxing, process isolation, or security restrictions.
Security Warning: This backend grants agents BOTH direct filesystem access AND unrestricted shell execution on your local machine. Use with extreme caution and only in appropriate environments.
Appropriate use cases:
Inappropriate use cases:
Use StateBackend, StoreBackend, or extend BaseSandbox for production.
class LocalShellBackendimport { LocalShellBackend } from "@langchain/deepagents";
// Create backend with explicit environment
const backend = new LocalShellBackend({
rootDir: "/home/user/project",
env: { PATH: "/usr/bin:/bin" },
});
// Execute shell commands (runs directly on host)
const result = await backend.execute("ls -la");
console.log(result.output);
console.log(result.exitCode);
// Use filesystem operations (inherited from FilesystemBackend)
const content = await backend.read("/README.md");
await backend.write("/output.txt", "Hello world");
// Inherit all environment variables
const backend2 = new LocalShellBackend({
rootDir: "/home/user/project",
inheritEnv: true,
});Enable virtual path mode for filesystem operations. When true, treats rootDir as a virtual root filesystem. Does NOT restrict shell commands.
Unique identifier for the sandbox backend
Mark the backend as no longer running.
For local shell backends there is no remote resource to tear down,
so this simply flips the isRunning / isInitialized flag.
Download multiple files from the sandbox. Implementations must support partial success.
Edit a file by replacing string occurrences.
Uses downloadFiles() to read, performs string replacement in TypeScript, then uploadFiles() to write back. No runtime needed on the sandbox host.
Execute a command in the sandbox. This is the only method concrete implementations must provide.
Structured glob matching returning FileInfo objects.
Uses pure POSIX shell (find + stat) via execute() to list all files, then applies glob-to-regex matching in TypeScript. No Python or Node.js needed on the sandbox host.
Glob patterns are matched against paths relative to the search base:
* matches any characters except /** matches any characters including / (recursive)? matches a single character except /[...] character classesSearch for a literal text pattern in files using grep.
Initialize the backend by ensuring the rootDir exists.
Creates the rootDir (and any parent directories) if it does not already
exist. Safe to call on an existing directory. Must be called before
execute(), or use the static LocalShellBackend.create() factory.
List files and directories in the specified directory (non-recursive).
Uses pure POSIX shell (find + stat) via execute() — works on any Linux including Alpine. No Python or Node.js needed.
Read file content with line numbers.
Uses pure POSIX shell (awk) via execute() — only the requested slice is returned over the wire, making this efficient for large files. Works on any Linux including Alpine (no Python or Node.js needed).
Read file content as raw FileData.
Uses downloadFiles() directly — no runtime needed on the sandbox host.
Upload multiple files to the sandbox. Implementations must support partial success.
Create a new file with content.
Uses downloadFiles() to check existence and uploadFiles() to write. No runtime needed on the sandbox host.
Create and initialize a new LocalShellBackend in one step.
This is the recommended way to create a backend when the rootDir may not exist yet. It combines construction and initialization (ensuring rootDir exists) into a single async operation.
Download multiple files from the sandbox.
Edit a file by replacing string occurrences.
Structured glob matching returning FileInfo objects.
Search for a literal text pattern in files using grep.
List files and directories in the specified directory (non-recursive).
Read file content with line numbers.
Read file content as raw FileData.
Upload multiple files to the sandbox.
Create a new file with content.