local_shell

This backend grants agents direct filesystem read/write access. Use with caution and only in appropriate environments.

Appropriate use cases:

• Local development CLIs (coding assistants, development tools)
• CI/CD pipelines (see security considerations below)

Inappropriate use cases:

• Web servers or HTTP APIs - use StateBackend, StoreBackend, or SandboxBackend instead

Security risks:

• Agents can read any accessible file, including secrets (API keys, credentials, .env files)
• Combined with network tools, secrets may be exfiltrated via SSRF attacks
• File modifications are permanent and irreversible

Recommended safeguards:

1. Enable Human-in-the-Loop (HITL) middleware to review sensitive operations
2. Exclude secrets from accessible filesystem paths (especially in CI/CD)
3. For production environments, prefer StateBackend, StoreBackend or SandboxBackend

In general, we expect this backend to be used with Human-in-the-Loop (HITL) middleware, or within a properly sandboxed environment if you need to run untrusted workloads.

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:

• Local development CLIs (coding assistants, development tools)
• Personal development environments where you trust the agent's code
• CI/CD pipelines with proper secret management (see security considerations)

Inappropriate use cases:

• Production environments (e.g., web servers, APIs, multi-tenant systems)
• Processing untrusted user input or executing untrusted code

Use StateBackend, StoreBackend, or extend BaseSandbox for production.

Security risks:

• Agents can execute arbitrary shell commands with your user's permissions
• Agents can read any accessible file, including secrets (API keys, credentials, .env files, SSH keys, etc.)
• Combined with network tools, secrets may be exfiltrated via SSRF attacks
• File modifications and command execution are permanent and irreversible
• Agents can install packages, modify system files, spawn processes, etc.
• No process isolation - commands run directly on your host system
• No resource limits - commands can consume unlimited CPU, memory, disk

Recommended safeguards:

Since shell access is unrestricted and can bypass filesystem restrictions:

1. Enable Human-in-the-Loop (HITL) middleware to review and approve ALL operations before execution. This is STRONGLY RECOMMENDED as your primary safeguard when using this backend.
2. Run in dedicated development environments only - never on shared or production systems
3. Never expose to untrusted users or allow execution of untrusted code
4. For production environments requiring code execution, extend BaseSandbox to create a properly isolated backend (Docker containers, VMs, or other sandboxed execution environments)