Filesystem
Run agent tasks in local temp directories
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.
On macOS and Linux, the filesystem provider automatically uses OS-level sandbox security for additional protection. See Sandbox Security below.
Overview
| Feature | Value |
|---|---|
| Isolation | Process-level + OS sandbox |
| Setup | None required |
| Performance | Fast startup |
| Use case | Development, trusted environments |
Configuration
# Default - no configuration needed
SANDBOX_PROVIDER=local
# Optional: customize base directory
SESSION_DIR_BASE=/tmp/sesameHow It Works
- Directory Structure: Creates a workspace at
{SESSION_DIR_BASE}/{sessionId}/
-
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 session completes
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 the Docker provider for better isolation.
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=falseOr configure via the admin panel at /admin/sandbox.
Per-Task Toggle
When creating a session, sandbox security can be enabled or disabled for that specific session. 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 session record
Violations appear in the session 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) |
SESSION_DIR_BASE | /tmp/sesame | Base directory for session workspaces |
Troubleshooting
Permission Errors
If you see permission errors when creating directories or running commands:
- Ensure the Sesame process has write access to
SESSION_DIR_BASE - Check that the base directory exists or can be created
- On Linux, ensure the user running Sesame has appropriate permissions
Disk Space
Sessions can consume significant disk space, especially with node_modules. Monitor disk usage and clean up old session directories periodically:
# Clean up old session directories (sessions 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 session cleanup should handle this, but if needed:
pkill -f "node.*sesame"