Sandboxing

Overview

Hawa Code provides native sandboxing to provide a more secure environment for agent execution while reducing the need for constant permission prompts. The sandbox mechanism creates defined boundaries upfront where Hawa Code can work more freely with reduced risk, without needing to request permission for each bash command.
The sandboxed bash tool uses OS-level primitives to enforce both filesystem and network isolation.

How It Works

Filesystem Isolation

The sandboxed bash tool restricts file system access to specific directories:

  • Default Write Behavior: Read and write access to the current working directory and its subdirectories
  • Default Read Behavior: Read access to the entire computer, except certain denied directories
  • Blocked Access: Cannot modify files outside the current working directory without explicit permission
  • Configurable: Define custom allowed and denied paths through settings

You can grant write access to additional paths using sandbox.filesystem.allowWrite in your settings. These restrictions are enforced at the OS level (Seatbelt on macOS, bubblewrap on Linux), so they apply to all subprocess commands, including tools like kubectl, terraform, and npm, not just Hawa Code’s file tools.

Network Isolation

Network access is controlled through a proxy server running outside the sandbox:

  • Domain Restrictions: Only approved domains can be accessed
  • User Confirmation: New domain requests trigger permission prompts (unless allowManagedDomainsOnly is enabled, which blocks non-allowed domains automatically)
  • Custom Proxy Support: Advanced users can implement custom rules on outgoing traffic
  • Comprehensive Coverage: Restrictions apply to all scripts, programs, and subprocesses spawned by commands

OS-level Enforcement

The sandboxed bash tool leverages operating system security primitives:

  • macOS: Uses Seatbelt for sandbox enforcement
  • Linux: Uses bubblewrap for isolation
  • WSL2: Uses bubblewrap, same as Linux

WSL1 is not supported because bubblewrap requires kernel features only available in WSL2.

These OS-level restrictions ensure that all child processes spawned by Hawa Code’s commands inherit the same security boundaries.

Getting Started

Prerequisites

On macOS, sandboxing works out of the box using the built-in Seatbelt framework.
On Linux and WSL2, install the required packages first:

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

Enable sandboxing

You can enable sandboxing by running the /sandbox command:

/sandbox

This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as bubblewrap or socat on Linux), the menu displays installation instructions for your platform.

Prev