Filesystem

The local filesystem sandbox provider is the default provider. It runs agent tasks directly on the host machine using temp directories and Bun's process spawning.

Overview

Feature	Value
Isolation	Process-level + OS sandbox
Setup	None required
Performance	Fast startup
Use case	Development, trusted environments

On macOS and Linux, the filesystem provider automatically uses OS-level sandbox security for additional protection. See Sandbox Security below.

Configuration

# Default - no configuration needed
SANDBOX_PROVIDER=local

# Optional: customize base directory
TASK_DIR_BASE=/tmp/sesame

How It Works

Directory Structure: Creates a workspace at {TASK_DIR_BASE}/{taskId}/

project

Command Execution: Uses Bun.spawn() to run commands directly on the host
Port Access: Dev servers run on localhost, accessible via http://localhost:{port}
Cleanup: Directories are removed when the task completes (unless keepAlive is enabled)

Advantages

Zero setup: Works out of the box with no additional dependencies
Fast startup: No container overhead
Direct access: Easy to debug - files are directly accessible on the host
Resource efficient: No containerization overhead

Limitations

Shared environment: All tasks share the host's installed tools and dependencies
Host access: Without sandbox security, processes run with the same permissions as the Sesame server

Without sandbox security enabled, this provider is not suitable for untrusted code execution. Enable sandbox security or use Docker for multi-tenant deployments.

Sandbox Security

On supported platforms (macOS and Linux), the filesystem provider integrates with @anthropic-ai/sandbox-runtime to provide OS-level restrictions.

What's Protected

When sandbox security is enabled:

Resource	Restriction
Filesystem (write)	Only project directory and `/tmp`
Filesystem (read)	Blocked: `~/.ssh`, `~/.aws`, `/etc/passwd`, credential files
Network	Only agent-specific API domains + configured allowlist

Enabling Sandbox Security

Sandbox security is enabled by default. To disable:

SANDBOX_SECURITY_ENABLED=false

Or configure via the admin panel at /admin/sandbox.

Per-Task Toggle

When creating a task, users can enable or disable sandbox security for that specific task. This is useful for:

Tasks that need to access external APIs not in the allowlist
Debugging sandbox-related issues
Legacy workflows that require broader access

Violation Monitoring

When sandbox security blocks an action, it:

Logs the violation with details (path or domain attempted)
Streams the violation to the UI via Server-Sent Events
Stores the violation in the task record for audit

Violations appear in the task detail view with the blocked resource and type (filesystem/network).

When to Use

The local provider is ideal for:

Local development and testing
Self-hosted deployments in trusted environments
Scenarios where Docker isn't available
Maximum performance with minimal overhead

Environment Variables

Variable	Default	Description
`SANDBOX_PROVIDER`	`local`	Set to `local` (or omit - it's the default)
`TASK_DIR_BASE`	`/tmp/sesame`	Base directory for task workspaces

Troubleshooting

Permission Errors

If you see permission errors when creating directories or running commands:

Ensure the Sesame process has write access to TASK_DIR_BASE
Check that the base directory exists or can be created
On Linux, ensure the user running Sesame has appropriate permissions

Disk Space

Tasks can consume significant disk space, especially with node_modules. Monitor disk usage and clean up old task directories periodically:

# Clean up old task directories (tasks older than 7 days)
find /tmp/sesame -maxdepth 1 -type d -mtime +7 -exec rm -rf {} \;

Process Cleanup

If tasks don't clean up properly, orphaned processes may remain:

# Find orphaned node processes
ps aux | grep node

# The task cleanup should handle this, but if needed:
pkill -f "node.*sesame"

On this page