Omnibox: OS Sandbox

Omnibox is Omnigent's flexible OS sandbox for any agent. It restricts filesystem access, network traffic, and environment variables at the OS level, letting you safely run agents with minimal permissions or lock them down for unattended YOLO-mode execution.

The OS sandbox restricts what commands and file operations your agent can perform. It controls which files the agent can read and write, whether it can access the network, and which environment variables it sees.

This is different from the cloud runner, which controls where the runner executes. The OS sandbox controls what the agent can access, regardless of where it runs.

The OS sandbox applies to the built-in OS tools (sys_os_read, sys_os_write, sys_os_edit, sys_os_shell) and any terminals you declare in the agent config.

Minimal config

The smallest useful OS sandbox. Make the working directory writable and let Omnigent pick the backend for your platform:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    write_paths: [.]          # cwd is read-only by default; opt it back in
    allow_network: true

On Linux, Omnigent uses bubblewrap (bwrap). On macOS, it uses Seatbelt (sandbox-exec). Omit type to auto-detect.

What you can restrict

Filesystem

By default, cwd is read-only on hardened backends. You opt in to writes explicitly.

sandbox:
  read_paths: [~/.gitconfig, ~/.ssh]        # read-only access outside cwd
  write_paths: [.]                          # writable directories
  write_files: [~/.ssh/known_hosts]         # individual writable files
  cwd_allow_hidden: [.venv, .git, .env]     # dotfiles to allow (rest are masked)

Dotfiles under cwd and read_paths are hidden by default unless listed in cwd_allow_hidden. This makes broad read grants safe: granting ~ doesn't expose ~/.aws/credentials or ~/.ssh/id_rsa. On macOS, ~/Library is also denied by default.

Network

sandbox:
  allow_network: true                       # basic on/off
  egress_rules:                             # optional HTTP(S) allow-list
    - "GET api.github.com/repos/myorg/**"   # GET only, one org
    - "* pypi.org/**"                       # any method
    - "* *.github.com/**"                   # wildcard subdomain

When egress_rules is set, all HTTP(S) traffic goes through a MITM proxy with default-deny. Only requests matching a rule are allowed. Requires a hardened backend (linux_bwrap or darwin_seatbelt).

Each rule is "METHODS host/path-glob": comma-separated HTTP verbs (or * for any), a hostname (or *.domain for subdomains), and a path glob where ** matches any depth.

By default, the proxy also blocks connections to private IPs (RFC1918, loopback, cloud metadata like 169.254.169.254). Set egress_allow_private_destinations: true if your agent needs to reach internal services.

Environment

sandbox:
  env_passthrough: [GH_TOKEN, AWS_PROFILE]  # only these vars reach the agent

The sandbox strips environment variables to a minimal default set (PATH, HOME, USER, LANG, etc.). Secrets only reach the agent if you name them explicitly.

Sharing a policy

Declare the sandbox once and reuse it with a YAML anchor:

os_env:
  type: caller_process
  cwd: .
  sandbox: &shared
    write_paths: [.]
    read_paths: [~/.gitconfig, ~/.ssh]
    allow_network: true

terminals:
  zsh:
    command: zsh
    os_env:
      type: caller_process
      cwd: .
      sandbox: *shared              # same policy as sys_os_* tools

Or use os_env: inherit on a terminal or sub-agent to inherit the parent's full environment including its sandbox.

In a multi-harness setup, each sub-agent defines its own sandbox in its own config.yaml file in the agents/ subdirectory. Agent entries in tools.agents are just names (strings), not inline config blocks.

# Parent config.yaml
tools:
  agents:
    - researcher
    - coder

# agents/researcher/config.yaml
os_env:
  sandbox:
    write_paths: [./research]
    allow_network: true

# agents/coder/config.yaml
os_env:
  sandbox:
    write_paths: [./src]
    allow_network: false

What is and isn't sandboxed

The OS sandbox applies to sys_os_* tool calls and terminals that reference the policy. It does not apply to:

• MCP servers. The runner spawns MCP subprocesses outside the sandbox. Constrain an MCP server at its own configuration site.
• The Omnigent supervisor process. It runs the model loop and dispatches tools. Only the commands it issues through OS tools run inside the sandbox.

If you ask for a sandbox (explicitly or via the default) and it can't be provided, Omnigent errors instead of quietly running unsandboxed. The only opt-out is sandbox.type: none.

Field reference

os_env

os_env.sandbox