# OpenHuman Sandbox Backend Isolation: Docker, Landlock, Seatbelt, and AppContainer Explained

> Discover how OpenHuman Sandbox backend isolation secures agent execution using Docker, Landlock, Seatbelt, and AppContainer. Learn about platform-specific sandboxing techniques.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-08-27

---

**OpenHuman isolates agent execution by routing external tool calls through platform-specific sandbox backends—Docker containers, Linux Landlock, macOS Seatbelt, or Windows AppContainer—depending on the agent's `sandbox_mode` and host operating system.**

The `tinyhumansai/openhuman` repository implements a robust sandboxing layer that prevents AI agents from accessing unauthorized host resources. When an agent operates in **Sandboxed** mode, the core execution engine intercepts all external tool calls—such as shell commands or code execution—and redirects them through an isolated backend rather than running them directly on the host. This architecture ensures that file-system, network, and process boundaries are enforced according to the capabilities of the underlying operating system.

## How OpenHuman Routes Execution Through Sandbox Backends

The isolation mechanism follows a three-phase workflow defined in [`src/openhuman/sandbox/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/sandbox/mod.rs). First, the system resolves the appropriate policy; then it dispatches to the specific backend implementation; finally, it normalizes the results for the agent.

**Policy Resolution**

The `sandbox::resolve_sandbox_policy` function examines the agent's `SandboxMode` setting and global configuration to determine which backend to activate. This configuration is declared in [`src/openhuman/config/ops/sandbox.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/config/ops/sandbox.rs), where the `SandboxMode` enum distinguishes between **Sandboxed**, **ReadOnly**, and **None** modes.

**Backend Dispatch**

Once resolved, `sandbox::execute_in_sandbox` receives the `SandboxPolicy`, command string, and action directory. It matches against the `SandboxBackend` enum to route execution:

```rust
match policy.backend {
    SandboxBackend::Docker => docker::run(policy, cmd, action_dir, extra_env).await,
    SandboxBackend::Landlock => landlock::run(policy, cmd, action_dir).await,
    SandboxBackend::Seatbelt => seatbelt::run(policy, cmd, action_dir).await,
    SandboxBackend::AppContainer => appcontainer::run(policy, cmd, action_dir).await,
    SandboxBackend::Noop => run_locally(cmd, action_dir, extra_env).await,
}

```

**Result Normalization**

Each backend returns a structured `SandboxResult` containing stdout, stderr, exit code, and diagnostics. Tool implementations such as `ShellTool` or `PythonExecTool` call `run_sandboxed`, which forwards commands to the sandbox layer and formats the output for the agent.

## Docker Backend Isolation

The **Docker** backend provides cross-platform isolation by spawning short-lived containers for each tool execution. When `SandboxBackend::Docker` is selected, the sandbox mounts only the agent's specific action directory into the container and routes all I/O through the container's network namespace.

After the tool completes, the container is immediately killed, ensuring no persistent processes remain. This implementation guarantees process, network, and file-system isolation independent of the host OS kernel version. Configuration options including the Docker image name are specified in the global sandbox settings located in [`src/openhuman/config/ops/sandbox.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/config/ops/sandbox.rs).

## Linux Landlock Backend Isolation

For Linux hosts running kernel version 5.13 or later, OpenHuman leverages **Landlock** to create kernel-level file-system sandboxes without requiring privileged containers.

The implementation resides in [`src/openhuman/sandbox/cwd_jail.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/sandbox/cwd_jail.rs). The `landlock::run` function constructs a Landlock ruleset that restricts all file-system accesses to the agent's sandbox directory. Before executing the target tool, the process applies these self-imposed restrictions, preventing escape from the whitelisted paths even if the process is compromised. This approach avoids the overhead of container startup while maintaining strict file-system boundaries.

## macOS Seatbelt Backend Isolation

On macOS, OpenHuman utilizes the native **Seatbelt** sandbox through the `sandbox-exec` utility. The [`cwd_jail.rs`](https://github.com/tinyhumansai/openhuman/blob/main/cwd_jail.rs) module contains platform-specific logic gated behind `#[cfg(target_os = "macos")]`.

When activated, the backend invokes `/usr/bin/sandbox-exec` with a profile that confines the process to its designated sandbox directory and denies network access unless explicitly permitted. This provides macOS-level sandboxing that is tightly integrated with the operating system's security model, ensuring agents cannot access files outside their assigned workspace or initiate unauthorized network connections.

## Windows AppContainer Backend Isolation

For Windows environments, OpenHuman supports **AppContainer** isolation when compiled with the `sandbox-appcontainer` feature flag. This backend constructs an AppContainer security token that limits the process to the sandbox folder and disables most system calls.

The implementation follows the same `execute_in_sandbox` entry point as other backends, selecting `appcontainer::run` when the policy dictates. This Windows-specific mechanism provides file-system and network confinement comparable to the Landlock and Seatbelt implementations on Unix systems.

## No-Op Fallback for Non-Sandboxed Agents

When an agent operates in **ReadOnly** or **None** mode, or when no sandbox backend is available, OpenHuman falls back to the **Noop** backend. This implementation executes tools directly in the host process without isolation via the `run_locally` function.

This mode is strictly used for agents that explicitly request reduced isolation or for development environments where sandboxing is disabled via feature flags. The `run_locally` path bypasses all containerization and kernel-level restrictions, executing with the full privileges of the host process.

## Implementing Sandbox Execution in Practice

Developers interacting with the OpenHuman sandbox layer can use the context helpers defined in [`src/openhuman/agent/harness/sandbox_context.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/harness/sandbox_context.rs). The `with_current_sandbox_mode` function allows temporary modification of the sandbox mode for specific operations:

```rust
use openhuman_core::openhuman::sandbox::{self, SandboxMode};
use openhuman_core::openhuman::agent::harness::with_current_sandbox_mode;

let result = with_current_sandbox_mode(SandboxMode::Sandboxed, async {
    // The tool automatically calls `run_sandboxed` internally
    tool.execute(json!({ "command": "ls -l /tmp" })).await
}).await;

println!("stdout: {}", result.output());

```

Global configuration is typically specified in an `.openhuman` configuration file:

```json
{
  "sandbox": {
    "enabled": true,
    "docker_image": "tinyhumansai/sandbox:latest",
    "firejail_args": ["--quiet"]
  }
}

```

The end-to-end tests in [`tests/cwd_jail_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/tests/cwd_jail_e2e.rs) verify that Landlock and Seatbelt protections correctly reject disallowed filesystem accesses, while separate integration tests validate Docker container isolation.

## Summary

- **Policy-driven isolation**: The `sandbox::resolve_sandbox_policy` function in [`src/openhuman/sandbox/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/sandbox/mod.rs) determines which backend to use based on the agent's `SandboxMode`.
- **Four backend options**: OpenHuman supports Docker (cross-platform), Landlock (Linux ≥5.13), Seatbelt (macOS), and AppContainer (Windows), plus a No-op fallback.
- **Kernel-level protection**: Landlock and Seatbelt implement operating-system-specific sandboxing without containers, while Docker provides full containerization.
- **Consistent interface**: All backends implement the same `SandboxResult` return type, allowing tool implementations like `ShellTool` to remain backend-agnostic.
- **Configurable per-agent**: The `sandbox_mode` setting in [`src/openhuman/config/ops/sandbox.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/config/ops/sandbox.rs) controls whether an agent runs sandboxed, read-only, or unrestricted.

## Frequently Asked Questions

### What determines which sandbox backend OpenHuman uses?

The backend selection depends on three factors: the agent's `SandboxMode` setting, the host operating system, and compiled feature flags. If the mode is set to **Sandboxed**, OpenHuman checks platform compatibility—using Landlock on Linux 5.13+, Seatbelt on macOS, and AppContainer on Windows (when the `sandbox-appcontainer` feature is enabled). Docker can be configured on any platform, and the No-op backend serves as a fallback when sandboxing is disabled or unavailable.

### How does OpenHuman prevent sandbox escape on Linux without Docker?

On Linux systems, OpenHuman uses the **Landlock** Linux Security Module (LSM) implemented in [`src/openhuman/sandbox/cwd_jail.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/sandbox/cwd_jail.rs). Before executing a tool, the process creates a ruleset that whitelists only the agent's action directory. The kernel enforces these restrictions at the system call level, preventing the process from accessing any files outside the permitted path tree, even if the tool attempts to traverse to parent directories or system folders.

### Can I use the Docker backend on macOS or Windows?

Yes, the Docker backend is platform-agnostic and functions on any operating system that can run the Docker daemon, including macOS and Windows. When configured, OpenHuman spawns a container for each tool execution, mounting only the necessary action directory. This provides consistent isolation across different development environments without requiring OS-specific sandboxing features like Seatbelt or AppContainer.

### What happens if I disable all sandbox features?

If all sandbox features are disabled or if an agent is configured with `SandboxMode::None`, OpenHuman routes execution through the **Noop** backend. This path calls `run_locally` to execute tools directly in the host process with full system access. While this eliminates isolation overhead, it should only be used for trusted agents in secure environments, as compromised tools could access any file or network resource available to the host user.