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

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. 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, 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:

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.

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. 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 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. The with_current_sandbox_mode function allows temporary modification of the sandbox mode for specific operations:

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:

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

The end-to-end tests in 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 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 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. 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.

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