Sandbox Mode

Freeact can restrict filesystem and network access for code execution and MCP servers using ipybox sandbox and Anthropic's sandbox-runtime.

Prerequisites

Check the installation instructions for sandbox mode prerequisites.

Code Execution

Scope

Sandbox restrictions apply equally to Python code and shell commands, as both execute in the same IPython kernel.

CLI Tool

The --sandbox option enables sandboxed code execution:

freeact --sandbox

A custom configuration file can override the default restrictions:

freeact --sandbox --sandbox-config sandbox-config.json

Agent SDK

The sandbox and sandbox_config parameters of the Agent constructor provide the same functionality:

from pathlib import Path

agent = Agent(
    ...
    sandbox=True,
    sandbox_config=Path("sandbox-config.json"),
)

Default Restrictions

Without a custom configuration file, sandbox mode applies these defaults:

• Filesystem: Read all files except .env, write to current directory and subdirectories
• Network: Internet access blocked, local network access to tool execution server permitted

Custom Configuration

sandbox-config.json

{
  "allowPty": true,
  "network": {
    "allowedDomains": ["example.org"],
    "deniedDomains": [],
    "allowLocalBinding": true
  },
  "filesystem": {
    "denyRead": ["sandbox-config.json"],
    "allowWrite": [".", "~/Library/Jupyter/", "~/.ipython/"],
    "denyWrite": ["sandbox-config.json"]
  }
}

This macOS-specific example configuration allows additional network access to example.org. Filesystem settings permit writes to ~/Library/Jupyter/ and ~/.ipython/, which is required for running a sandboxed IPython kernel. The sandbox configuration file itself is protected from reads and writes.

MCP Servers

MCP servers run as separate processes and are not affected by code execution sandboxing. Local stdio servers can be sandboxed independently by wrapping the server command with the srt tool from sandbox-runtime. This applies to both mcp_servers and ptc_servers in the configuration file.

Filesystem MCP Server

This example shows a sandboxed filesystem MCP server in the mcp_servers section:

.freeact/agent.json

{
  "mcp_servers": {
    "filesystem": {
      "command": "srt",
      "args": [
        "--settings", "sandbox-filesystem-mcp.json",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "."
      ]
    }
  }
}

The sandbox configuration blocks .env reads and allows network access to the npm registry, which is required for npx to download the server package:

sandbox-filesystem-mcp.json

{
  "filesystem": {
    "denyRead": [".env"],
    "allowWrite": [".", "~/.npm"],
    "denyWrite": []
  },
  "network": {
    "allowedDomains": ["registry.npmjs.org"],
    "deniedDomains": [],
    "allowLocalBinding": true
  }
}

Fetch MCP Server

This example shows a sandboxed fetch MCP server. First, install it locally with:

uv add mcp-server-fetch
uv add "httpx[socks]>=0.28.1"

Then add it to the ptc_servers section:

.freeact/agent.json

{
  "ptc_servers": {
    "fetch": {
      "command": "srt",
      "args": [
        "--settings", "sandbox-fetch-mcp.json",
        "python", "-m", "mcp_server_fetch"
      ]
    }
  }
}

The sandbox configuration blocks .env reads and restricts the MCP server to fetch only from example.com. Access to the npm registry is required for the server's internal operations:

sandbox-fetch-mcp.json

{
  "filesystem": {
    "denyRead": [".env"],
    "allowWrite": [".", "~/.npm", "/tmp/**", "/private/tmp/**"],
    "denyWrite": []
  },
  "network": {
    "allowedDomains": ["registry.npmjs.org", "example.com"],
    "deniedDomains": [],
    "allowLocalBinding": true
  }
}