Greywall — Sandbox for AI Coding Agents

Greywall is a container-free sandbox for AI coding agents on Linux and macOS, with two complementary modes:

• greywall — deny-by-default sandbox. Restricts filesystem access, network connections, and system calls to only what you explicitly allow, so tools like Claude Code, Cursor, Codex, and other AI agents can't reach your SSH keys, secrets, or anything outside the working directory.
• greywatch — allow-by-default observability layer (equivalent to greywall --watch). Skips profile loading, registers a */* allow rule with greyproxy so every network request is accepted but logged on the dashboard, and runs with a permissive filesystem. Use it to see what a tool actually does before deciding what to lock down.

Both modes route every network connection through greyproxy — a transparent proxy with a live allow/deny dashboard — so traffic stays visible whether you're enforcing or observing. Use --learning to trace what a command needs and auto-generate a least-privilege config profile.

Supports Linux and macOS. See platform support for details.

0304.mp4

Key features

• Deny-by-default filesystem — only the working directory is accessible unless you allow more
• Network isolation — all traffic blocked or routed through greyproxy with a live dashboard
• Command blocking — dangerous commands like rm -rf / and git push --force are denied
• Built-in agent profiles — one-command setup for Claude Code, Cursor, Codex, Aider, Goose, Gemini, OpenCode, Amp, Cline, Copilot, and more
• Learning mode — traces filesystem access and auto-generates least-privilege profiles
• Observability mode — greywatch (or greywall --watch) runs commands with no profile and all network allowed, so the greyproxy dashboard shows exactly what an agent does without anything being denied
• Five security layers on Linux — Bubblewrap namespaces, Landlock, Seccomp BPF, eBPF monitoring, TUN-based network capture
• No containers required — kernel-enforced sandboxing without Docker overhead

# Sandbox a command (network + filesystem denied by default)
greywall -- curl https://example.com

# Sandbox an AI coding agent with a built-in profile
greywall -- claude

# Observe what an agent does without blocking anything (allow-by-default)
greywatch -- claude

# Learn what filesystem access a command needs, then auto-generate a profile
greywall --learning -- opencode

# Block dangerous commands
greywall -c "rm -rf /"  # → blocked by command deny rules

Install

Homebrew (macOS):

brew tap greyhavenhq/tap
brew install greywall

This also installs greyproxy as a dependency.

Linux / Mac:

curl -fsSL https://raw.githubusercontent.com/GreyhavenHQ/greywall/main/install.sh | sh

Both greywall and the greywatch alias (observability mode) are installed by Homebrew, install.sh, and make build. greywatch is a symlink to the same binary — argv[0] dispatch enables --watch automatically.

Other installation methods

Go install:

go install github.com/GreyhavenHQ/greywall/cmd/greywall@latest
# Create the greywatch alias yourself (Go install ships a single binary):
ln -s "$(go env GOPATH)/bin/greywall" "$(go env GOPATH)/bin/greywatch"

mise:

mise use -g github:GreyhavenHQ/greywall
mise use -g github:GreyhavenHQ/greyproxy

Manual tarball: GitHub release tarballs contain only the greywall binary. After extracting, create the alias yourself:

ln -s greywall greywatch

Build from source:

git clone https://github.com/GreyhavenHQ/greywall
cd greywall
make setup && make build   # creates ./greywall and ./greywatch symlink

Linux dependencies:

• bubblewrap - container-free sandboxing (required)
• socat - network bridging (required)
• xdg-dbus-proxy - filtered D-Bus proxy for notify-send support (optional)
• libsecret-tools - keyring credential injection for gh/glab (optional)

Check dependency status with greywall check.

Usage

Basic commands

# Run with all network blocked (default)
greywall -- curl https://example.com

# Run with shell expansion
greywall -c "echo hello && ls"

# Route through a SOCKS5 proxy
greywall --proxy socks5://localhost:1080 -- npm install

# Expose a port for inbound connections (e.g., dev servers)
greywall -p 3000 -c "npm run dev"

# Enable debug logging
greywall -d -- curl https://example.com

# Monitor sandbox violations
greywall -m -- npm install

# Show available Linux security features
greywall --linux-features

# Show version
greywall --version

# Check dependencies, security features, and greyproxy status
greywall check

# Install and start greyproxy
greywall setup

Agent profiles

Greywall ships with built-in sandbox profiles for popular AI coding agents (Claude Code, Codex, Cursor, Aider, Goose, Gemini CLI, OpenCode, Amp, Cline, Copilot, Kilo, Auggie, Droid) and toolchains (Node, Python, Go, Rust, Java, Ruby, Docker).

On first run, greywall shows what the profile allows and lets you apply, edit, or skip:

$ greywall -- claude

[greywall] Running claude in a sandbox.
A built-in profile is available. Without it, only the current directory is accessible.

Allow read:  ~/.claude  ~/.claude.json  ~/.config/claude  ~/.local/share/claude  ~/.gitconfig  ...  + working dir
Allow write: ~/.claude  ~/.claude.json  ~/.cache/claude  ~/.config/claude  ...  + working dir
Deny read:   ~/.ssh/id_*  ~/.gnupg/**  .env  .env.*
Deny write:  ~/.bashrc  ~/.zshrc  ~/.ssh  ~/.gnupg

[Y] Use profile (recommended)   [e] Edit first   [s] Skip (restrictive)   [n] Don't ask again
>

Combine agent and toolchain profiles with --profile:

# Agent + Python toolchain (allows access to ~/.cache/uv, ~/.local/pipx, etc.)
greywall --profile claude,python -- claude

# Agent + multiple toolchains
greywall --profile opencode,node,go -- opencode

# List all available and saved profiles
greywall profiles list

Learning mode

Greywall can trace a command's filesystem access and generate a config profile automatically:

# Run in learning mode - traces file access via strace
greywall --learning -- opencode

# List generated profiles
greywall profiles list

# Show a profile's content
greywall profiles show opencode

# Next run auto-loads the learned profile
greywall -- opencode

Watch mode (observability)

Watch mode flips the policy: no profile is loaded, every network request is accepted but logged on the greyproxy dashboard, and the local filesystem is permissive. Use it to see what a tool does before deciding what to restrict — the inverse of deny-by-default.

# Same thing, two entry points
greywatch -- claude
greywall --watch -- claude

# Inspect what claude touches in the greyproxy dashboard:
#   http://localhost:43080

What stays the same:

• Network traffic still goes through greyproxy. On Linux, --unshare-net + tun2socks force it; on macOS, the Seatbelt profile blocks direct egress to anything except the proxy. The dashboard sees every request.
• Hard safety floor remains. Mandatory denies (~/.ssh/authorized_keys, git hooks, etc.) still apply even with the permissive filesystem.
• Credential substitution stays on by default (disable with --no-credential-protection).

What changes vs. normal mode:

• No profile is loaded — observability runs from a blank default config.
• A single */* allow rule is registered with greyproxy for the session, so nothing is denied.
• Filesystem deny-by-default is off and the command deny list is disabled.

-m (violation monitor) stays orthogonal — combine --watch -m if you want both.

Configuration

Greywall reads from ~/.config/greywall/greywall.json by default (or ~/Library/Application Support/greywall/greywall.json on macOS).

{
  // Route traffic through an external SOCKS5 proxy
  "network": {
    "proxyUrl": "socks5://localhost:1080",
    "dnsAddr": "localhost:5353"
  },
  // Control filesystem access
  "filesystem": {
    "defaultDenyRead": true,
    "allowRead": ["~/.config/myapp"],
    "allowWrite": ["."],
    "denyWrite": ["~/.ssh/**"],
    "denyRead": ["~/.ssh/id_*", ".env"]
  },
  // Block dangerous commands
  "command": {
    "deny": ["git push", "npm publish"]
  }
}

Use greywall --settings ./custom.json to specify a different config file.

By default, traffic routes through the GreyProxy SOCKS5 proxy at localhost:43052 with DNS via localhost:43053.

Platform support

Feature	Linux	macOS
Sandbox engine	bubblewrap	sandbox-exec (Seatbelt)
Filesystem deny-by-default (read/write)	✅	✅
Syscall filtering	✅ (seccomp)	✅ (Seatbelt)
Filesystem access control	✅ (Landlock + bubblewrap)	✅ (Seatbelt)
Violation monitoring	✅ (eBPF)	✅ (Seatbelt denial logs)
Transparent proxy (full traffic capture)	✅ (tun2socks + TUN)	❌
DNS capture	✅ (DNS bridge)	❌
Proxy via env vars (SOCKS5 / HTTP)	✅	✅
Network isolation	✅ (network namespace)	N/A
Command allow/deny lists	✅	✅
Environment sanitization	✅	✅
Learning mode	✅ (strace)	✅ (eslogger, requires sudo)
PTY support	✅	✅
External deps	bwrap, socat, xdg-dbus-proxy (optional)	none

See platform support for more details.

Greywall can also be used as a Go package.

Documentation

Full documentation is available at https://docs.greywall.io/greywall.

• Quickstart Guide
• Why Greywall
• Configuration Reference
• Learning Mode
• Security Model
• Architecture
• Platform Support
• Linux Security Features
• AI Agent Integration
• Library Usage (Go)
• Troubleshooting

Attribution

Greywall is a fork of Fence, originally created by JY Tan at Tusk AI, Inc. Copyright 2025 Tusk AI, Inc. Licensed under the Apache License 2.0.

Inspired by Anthropic's sandbox-runtime.