How the Sandbox Confinement Feature in Reasonix Limits the Blast Radius of Tool Calls

Reasonix isolates every shell command invocation inside an OS-level sandbox defined by sandbox.Spec, enforcing strict controls on filesystem writes, blocking reads from sensitive paths, and disabling network access unless explicitly permitted.

The DeepSeek-Reasonix repository implements a defense-in-depth security architecture where the sandbox confinement feature acts as a mandatory access control layer for all tool executions. By leveraging platform-specific sandbox backends, Reasonix ensures that even if a language model generates a malicious or buggy command, the underlying process remains physically incapable of modifying system files, accessing secrets, or establishing unauthorized network connections.

Core Sandbox Mechanisms in Reasonix

Enforcement Mode and Platform Backends

The sandbox.Spec struct defines the confinement policy, with the Mode field determining enforcement behavior. When Spec.Mode is set to "enforce", Reasonix wraps the command using the platform-specific backend: bubblewrap on Linux or sandbox-exec on macOS.

Crucially, if the specified backend is missing from the host system, Reasonix aborts the tool call with a clear error rather than falling back to unconfined execution. This fail-closed design prevents accidental exposure of the host environment. According to the source code in internal/sandbox/sandbox.go (lines 69-84), the system validates backend availability before attempting execution, ensuring that security boundaries cannot be silently bypassed due to missing dependencies.

Filesystem Isolation via Write Roots and Forbidden Reads

The sandbox strictly limits filesystem interactions through two complementary controls:

• WriteRoots – As defined in internal/sandbox/sandbox.go (lines 27-33), this field specifies the only directories where the sandboxed process may write. By default, this includes the workspace root, preventing tools from arbitrarily overwriting files elsewhere on the host system.
• ForbidReadRoots – Enumerated in internal/sandbox/sandbox.go (lines 43-48), this list defines paths that must remain invisible to the sandboxed process (such as /etc/passwd or SSH keys). The backend blocks all read attempts from these locations, guaranteeing that tools cannot leak protected data even if instructed to do so.

Network Egress Control

The Network boolean flag in sandbox.Spec controls outbound connectivity. When set to false (the default for high-security configurations), the sandbox backend denies all socket creation attempts, eliminating exfiltration vectors. This is implemented in internal/sandbox/sandbox.go (lines 48-51), where the flag directly translates to platform-specific network namespace restrictions or firewall rules.

Integration with Tool Execution

Automatic Confinement of Bash Commands

The built-in bash tool is created by the ConfineBash function located in internal/tool/builtin/confine.go (lines 19-31). This wrapper automatically injects the sandbox specification into every invocation. Additionally, the SessionDataGuard component ensures that the sandbox arguments are applied automatically by setting args["sandbox"] = true before execution.

This integration guarantees that every shell command processed by Reasonix inherits the confinement policy without requiring manual configuration per call. The following example demonstrates how the bash tool receives sandbox arguments automatically:

// Invoking the bash tool from a Reasonix session
// The sandbox spec is injected automatically by the tool-guard
args := map[string]any{
    "command": "npm install", // Runs inside the sandbox
    "sandbox": true,          // Injected by SessionDataGuard
}
output, err := tool.Execute(ctx, args)

Fail-Closed Security Design

If the sandbox backend is unavailable or the Mode is set to "enforce" but the platform lacks support, Reasonix fails closed. The tool execution returns an error immediately rather than proceeding with unconfined privileges. This behavior ensures that security policy violations cannot occur due to configuration drift or missing system dependencies.

Configuration and Implementation Examples

You can configure sandbox behavior globally via reasonix.toml or programmatically via the Go API.

Global configuration file:

// reasonix.toml – enable sandbox for all bash tools
[sandbox]
bash = "enforce"          # wrap bash calls in OS sandbox

workspace_root = "./"     # default write root (the project folder)

allow_write = []          # additional safe write directories, if needed

network = false           # disallow network egress by default

Manual specification for custom tools:

import "github.com/esengine/DeepSeek-Reasonix/internal/sandbox"

// Manually creating a sandbox spec for a custom tool
spec := sandbox.Spec{
    Mode:            "enforce",
    WriteRoots:      []string{"/home/user/project"},
    Network:         false,
    ForbidReadRoots: []string{"/etc/passwd", "/home/user/.ssh"},
}
myTool := sandbox.ConfineSearch(searchSpec, spec, []string{"/tmp/secret"})

Summary

• Reasonix uses sandbox.Spec to define OS-level confinement boundaries for every tool invocation.
• The enforcement mode supports bubblewrap (Linux) and sandbox-exec (macOS), aborting execution if backends are missing rather than falling back to unconfined mode.
• WriteRoots restricts file modifications to the workspace and explicitly allowed directories, while ForbidReadRoots blocks access to sensitive paths like credential stores.
• The Network flag controls outbound connectivity, preventing data exfiltration when disabled.
• The ConfineBash function in internal/tool/builtin/confine.go ensures automatic application of sandbox policies to all shell commands.

Frequently Asked Questions

What happens if the sandbox backend is not installed on the host system?

Reasonix aborts the tool call with an explicit error and does not execute the command. According to the implementation in internal/sandbox/sandbox.go (lines 69-84), the system validates backend availability before execution and fails closed to prevent accidental unconfined execution.

Can sandboxed tools write to directories outside the workspace?

No, unless explicitly permitted. The WriteRoots field in sandbox.Spec defines the only writable locations. By default, this is limited to the workspace root, ensuring that tools cannot overwrite system files or user data in other directories.

How does Reasonix handle network access for sandboxed commands?

The Network boolean in sandbox.Spec controls egress. When set to false, the sandbox backend blocks all outbound network connections. This prevents sandboxed tools from contacting external APIs or exfiltrating data, as enforced at the OS level in internal/sandbox/sandbox.go (lines 48-51).

Is the sandbox confinement feature available on Windows?

Windows support currently runs unconfined with the sandbox mode set to "off". The enforcement backends (bubblewrap and sandbox-exec) are specific to Linux and macOS respectively. On Windows, Reasonix does not provide OS-level confinement through this mechanism, though the tool-guard architecture remains consistent across platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}