# How to Set Up Sandbox and Workspace_Root Constraints for File Operations in Reasonix

> Learn to set up Reasonix sandbox and workspace_root constraints for secure file operations. Configure allow_write paths and enforce OS-level jails for enhanced security.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-24

---

**TLDR:** Reasonix isolates file-write operations using a sandbox configured in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) where `workspace_root` defines the base directory and `allow_write` lists additional permitted paths, enforced via OS-level jails on macOS when `mode = "enforce"`.

The `esengine/DeepSeek-Reasonix` repository implements a security model that constrains AI-driven file operations to designated directories. By configuring **sandbox and workspace_root constraints for file operations in Reasonix**, you prevent unauthorized writes outside your project boundaries while maintaining flexibility for temporary or data directories. This system ensures that tools like `write_file`, `edit_file`, and `move_file` cannot escape the intended directory hierarchy.

## Understanding the Sandbox Architecture

Reasonix employs a sandbox that acts as a jail for the built-in Bash tool, which executes all file-writing commands. The configuration resides in a [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file and controls two primary security boundaries.

### Core Configuration Parameters

The sandbox recognizes two critical settings that define the write perimeter:

- **`workspace_root`**: The absolute base directory that any file-writer may touch. When set to an empty string (`""`), it defaults to the current working directory at runtime. Paths outside this directory are rejected.
- **`allow_write`**: A list of additional absolute paths permitted for writes (e.g., `/tmp`, user data directories). By default, this list is empty.

### Enforcement Modes

The `mode` setting determines whether the sandbox is active:

- **`enforce`**: Activates OS-level sandboxing using macOS Seatbelt. On other operating systems, this runs unconfined.
- **`off`**: Disables sandbox restrictions entirely.

The default is `"enforce"` for macOS and `"off"` for Linux and Windows.

## Configuring the Sandbox in reasonix.toml

To activate constraints, create or modify [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) in your project root:

```toml
[sandbox]
mode = "enforce"
workspace_root = "/absolute/path/to/project"
allow_write = ["/tmp", "/home/user/data"]

```

Save the file and restart Reasonix. The configuration reloads automatically, applying the new constraints to subsequent file operations.

## Implementation Deep Dive

The constraint system spans multiple packages in the `esengine/DeepSeek-Reasonix` codebase, from configuration rendering to runtime enforcement.

### Configuration Rendering in render.go

The [`internal/config/render.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/render.go) file handles emitting the sandbox section into the generated TOML. Lines 388–394 contain the explanatory comment describing write restrictions, while lines 392–394 handle the emission of the `workspace_root` value when present. This ensures the `sandbox.Spec` struct is correctly populated from the configuration file.

### Runtime Enforcement in confine.go and sandbox.go

The actual enforcement logic resides in [`internal/tool/builtin/confine.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/builtin/confine.go). At line 85–87, the code constructs a `sandbox.Spec` containing the `WorkspaceRoot` and `AllowWrite` entries, then passes this specification to the Bash tool wrapper. The comment explicitly states that writes are only allowed inside the workspace root or any `allow_write` entries.

The core implementation lives in [`internal/sandbox/sandbox.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/sandbox/sandbox.go):

- **Lines 1–28**: Define the `Spec` struct containing `WorkspaceRoot` and `AllowWrite` fields, along with the package description.
- **Lines 11–20**: Implement the `Command` function that builds the `sandbox-exec` command on macOS, returning the argv array that runs the command inside the OS sandbox.

When `sandbox.Available()` returns false (on non-macOS systems), commands run unconfined. The [`doctor/report.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/doctor/report.go) file (lines 80–84) marks the sandbox as inactive in these cases.

### Desktop Workspace Persistence

For desktop UI users, [`desktop/workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace.go) manages the last accessed folder under the user's Reasonix config directory (`desktop-workspace`). Lines 21–27 and 38–46 handle reading and writing this state. While this provides a default `workspace_root`, the sandbox constraints still apply to any file-writer invoked from the UI.

## Runtime Behavior and Constraints

Understanding how the sandbox behaves at runtime prevents unexpected failures during file operations.

- **Write Restrictions**: Any write attempt resolving outside `workspace_root` and not listed in `allow_write` causes the sandbox to abort and return an error (e.g., `write outside root should be denied by the sandbox`). This behavior is verified in [`confine_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/confine_test.go) at line 162.
- **Read Permissions**: The sandbox only restricts write operations; read operations remain unrestricted regardless of path.
- **Path Resolution**: Relative paths like [`../outside.txt`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/../outside.txt) are resolved against `workspace_root` and rejected if the absolute result falls outside the allowed boundary.

## Practical Implementation Example

Below is a minimal Go example demonstrating how Reasonix invokes a file-write tool that respects the sandbox constraints:

```go
// Configure the sandbox specification
spec := sandbox.Spec{
    Mode:          "enforce",
    WorkspaceRoot: "/home/alice/projects/myapp",
    AllowWrite:    []string{"/tmp"},
}

// Initialize the Bash tool with sandbox confinement
bashTool := tool.Builtin("bash", sandbox.Spec{
    Mode:          "enforce", 
    WorkspaceRoot: spec.WorkspaceRoot,
})

// Execute a write operation - this will succeed
result, err := bashTool.Run(ctx, "write_file", map[string]any{
    "path":    "src/main.go",  // Resolves to /home/alice/projects/myapp/src/main.go
    "content": "package main\nfunc main() {}",
})

// This would fail - resolves outside workspace_root
// result, err := bashTool.Run(ctx, "write_file", map[string]any{
//     "path": "../outside.txt",
// })

```

## Summary

- **Sandbox Configuration**: Define `workspace_root` and `allow_write` in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) to restrict file operations to specific directories.
- **OS Enforcement**: macOS uses Seatbelt for OS-level jailing when `mode = "enforce"`; other platforms run unconfined.
- **Source Locations**: Configuration renders via [`internal/config/render.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/render.go), enforcement logic lives in [`internal/tool/builtin/confine.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/builtin/confine.go) and [`internal/sandbox/sandbox.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/sandbox/sandbox.go), and desktop state persists in [`desktop/workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace.go).
- **Security Model**: Writes are strictly confined to `workspace_root` plus explicit `allow_write` paths, while reads remain unrestricted.

## Frequently Asked Questions

### What happens if I don't set workspace_root?

If `workspace_root` is omitted or set to an empty string in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), Reasonix defaults to the current working directory at runtime. However, this is less secure than explicit configuration, as the effective root depends on where the process starts.

### How does the sandbox behave on Linux or Windows?

On Linux and Windows, `sandbox.Available()` returns false, causing the Bash tool to run unconfined regardless of the `mode` setting. The [`doctor/report.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/doctor/report.go) module will indicate the sandbox is inactive. Reasonix currently only implements OS-level jailing via macOS Seatbelt.

### Can I allow writes outside the workspace_root?

Yes, by adding absolute paths to the `allow_write` array in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml). For example, `allow_write = ["/tmp", "/var/log/myapp"]` permits writes to those specific directories even if they fall outside `workspace_root`. All other external paths remain blocked when `mode = "enforce"`.

### Where does Reasonix store the desktop workspace state?

The desktop application persists the last used folder in the user's Reasonix configuration directory under the `desktop-workspace` key. The [`desktop/workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace.go) file handles this storage at lines 21–27 and 38–46, retrieving the stored path to use as the default `workspace_root` in subsequent sessions.