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

> Discover how Reasonix sandbox confinement protects your system by isolating tool calls, strictly controlling filesystem access, and disabling network access by default.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: internals
- Published: 2026-08-07

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```go
// 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) or programmatically via the Go API.

**Global configuration file:**

```go
// 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:**

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.