# 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

# 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

Go install:

go install github.com/GreyhavenHQ/greywall/cmd/greywall@latest

mise:

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

Build from source:

git clone https://github.com/GreyhavenHQ/greywall
cd greywall
make setup && make build

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

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.