Sandbox

OpenWalrus can run agent workloads under a dedicated walrus system user, providing OS-level isolation without containers or VMs. This keeps your home directory safe from unintended file access.

How it works

The sandbox creates a real OS user named walrus with its own home directory. Agents running in sandbox mode execute as this user, so they can only access files you've explicitly shared.

This is not runtime sandboxing — it uses standard Unix permissions and ACLs. The walrus user has no special privileges and cannot escalate.

Setting up the sandbox

Initialize

Create the walrus system user and its directory structure:

sudo walrus sandbox init

This creates:

On macOS, init uses dscl to create the user. On Linux, it uses useradd --system.

Share files

Grant the walrus user access to a directory on your host:

# Full read-write access
walrus sandbox share /path/to/project

# Read-only access
walrus sandbox share /path/to/project --read-only

# Copy into sandbox workspace (COW clone on supported filesystems)
walrus sandbox share /path/to/project --copy --into my-project

ACL method depends on platform:

• macOS — chmod +a "walrus allow ..." (recursive)
• Linux — setfacl -R -m u:walrus:rwX with default ACL propagation for new files

The --copy --into mode copies the directory into ~/workspaces/<name> and chowns it to walrus. On macOS this uses cp -Rc (COW clonefile), on Linux cp -R --reflink=auto.

Revoke access

Remove the walrus user's ACL entries from a path:

walrus sandbox unshare /path/to/project

Check status

List sandbox state and shared workspaces:

walrus sandbox shared

Permission bypass

When the daemon detects it's running as the walrus user, it sets sandboxed = true. In sandbox mode, OS tools (read, write, edit, bash) bypass the permission layer entirely — no ask prompts, no deny blocks.

The rationale: the OS already constrains what the walrus user can touch. Adding a second permission layer on top would be redundant.

Platform support

The sandbox command is Unix-only (#[cfg(unix)]). It is not available on Windows.

What's next

• Permissions — the software permission layer for non-sandboxed setups
• Built-in tools — the tools affected by sandbox mode
• CLI reference — full command syntax