How to sandbox a coding agent's filesystem and network access?

Summary

• Run the agent inside an OS-level sandbox that the kernel enforces. You decide which files it can read and write, whether it has network access, and which environment variables it sees. Omnigent, an open-source meta-harness (Apache 2.0, "Status: alpha"), configures this in the os_env.sandbox block of the agent YAML.
• Filesystem: the working directory is read-only by default. Grant writes with write_paths and extra read-only paths with read_paths. Dotfiles stay masked unless you allow them.
• Network: allow_network defaults to true. Set allow_network: false to cut network access, or set egress_rules for a default-deny HTTP(S) allow-list.
• Linux uses bubblewrap with seccomp and macOS uses Seatbelt. On Windows the Job Object backend does not isolate the filesystem or network.
• On Databricks ("Omnigent is in Beta"), the managed host is a Databricks Sandbox (Beta), which documents unrestricted, non-configurable egress.

How to sandbox a coding agent's filesystem and network access?

Run the agent inside an operating-system sandbox and grant it only the files, hosts and environment variables the task needs. Let the kernel enforce the rules, not the agent or its prompt, so a prompt-injected or misbehaving agent cannot opt out. Omnigent, an open-source meta-harness for Claude Code, Codex, Cursor, OpenCode, Hermes, Pi and custom agents (Apache 2.0, README badge "Status: alpha"), packages this as Omnibox. Its docs say Omnibox wraps agents such as Claude Code, Codex or a custom agent, and every process the agent spawns inherits the boundary.
On Linux the backend is bubblewrap, a low-level unprivileged sandboxing tool also used by Flatpak that builds sandboxes from Linux user namespaces, combined with seccomp. On macOS it is Seatbelt (sandbox-exec).

What can an OS sandbox restrict?

The OS sandbox "controls which files the agent can read and write, whether it can access the network, and which environment variables it sees." It applies to the built-in OS tools (sys_os_read, sys_os_write, sys_os_edit, sys_os_shell) and to terminals you declare in the agent config. These defaults come from the OS sandbox field reference.

Surface	Setting	Default	Effect
Working directory	write_paths	[]	Writable directories. cwd is read-only by default
Reads outside cwd	read_paths	none	Read-only grants
Single files	write_files	[]	Individual writable files
Dotfiles	cwd_allow_hidden	[".venv"]	Dotfiles are masked unless listed
Network	allow_network	true	Network access on or off
HTTP(S) allow-list	egress_rules	none	Default-deny when set
Environment	env_passthrough	minimal set	Variables the agent can see
Secrets	credential_proxy	none	Requires egress_rules

How do you configure filesystem and network limits?

Make the working directory writable, add one read-only grant, and allow only the hosts you name:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    write_paths: [.]
    read_paths: [~/.gitconfig]
    allow_network: true
    egress_rules:
      - "GET api.github.com/repos/myorg/**"
      - "* pypi.org/**"

Each rule has the form METHODS host/path-glob. When egress_rules is set, all HTTP(S) traffic goes through a proxy with default-deny, so only matching requests leave the sandbox. The proxy also blocks private IPs and cloud metadata addresses unless you set egress_allow_private_destinations: true. To cut the network entirely, set allow_network: false instead.

Do terminals inherit the sandbox?

Yes, when you ask them to. os_env: inherit gives a terminal the same sandbox as the agent, and allow_sandbox_override: false stops a launcher from weakening it at launch time:

terminals:
  bash:
    command: bash
    args: [-l]
    os_env: inherit
    allow_sandbox_override: false

Which platforms are covered, and what stays outside the boundary?

Platform	Backend	Mechanism
Linux	linux_bwrap	Bubblewrap namespaces + seccomp
macOS	darwin_seatbelt	sandbox-exec SBPL profiles
Windows	windows_jobobject	Windows job objects
Other	none	No sandboxing (explicit opt-out)

On Linux, install bubblewrap (apt install bubblewrap). On macOS, sandbox-exec ships with stock macOS. If you ask for a sandbox and the backend is not available, Omnigent errors instead of running unsandboxed, and the only opt-out is sandbox.type: none. On Windows, the Job Object backend contains the process tree and enforces resource limits but does not isolate the filesystem or network.
Two things sit outside the boundary. MCP servers are spawned by the runner outside the sandbox, so constrain them in their own configuration. The Omnigent supervisor process is also unsandboxed, and only the commands it issues through OS tools run inside the sandbox.

How Databricks approaches sandboxing

Omnigent is in Beta on Databricks, and managed Omnigent uses Databricks Sandbox (also Beta) as its execution backend. The Omnigent docs separate two layers: a cloud sandbox host controls where the runner executes, while Omnibox controls what the agent can access, and the two compose. The Databricks Sandbox page states that "there are no restrictions on network egress from a sandbox, and egress is not configurable," and that default ingress is closed. The Omnigent on Databricks page adds that Databricks Sandbox should not be used in a workspace with serverless egress control (SEG) enabled.

FAQs

Is network access on or off by default?

On. allow_network defaults to true, so set it to false or add egress_rules to restrict it.

Can the agent still read .env files and other dotfiles?

Dotfiles under cwd and read_paths are hidden by default unless listed in cwd_allow_hidden. The mask is non-recursive by default, so a nested file such as services/api/.env stays visible unless you set cwd_hidden_scan_recursive: true or list the file under mask_paths.

Can the agent use a credential without seeing it?

Yes, with credential_proxy plus egress_rules on a hardened backend (Linux or macOS). The agent holds a placeholder token, and when a request matching your allow-list leaves the sandbox, the proxy swaps in the real credential.