Greywall

Greywall wraps commands in a deny-by-default sandbox. Filesystem access is restricted to the current directory by default. Use --learning to trace what else a command needs and auto-generate a config profile. All network traffic is transparently redirected through greyproxy, a deny-by-default transparent proxy with a live allow/deny dashboard. Run greywall setup to install greyproxy automatically.

Supports Linux and macOS. See platform support for details.

0304.mp4

# Check that greywall installation is ok
greywall check

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

# 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

Other installation methods

Go install:

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

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)

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 profiles for popular AI coding agents (Claude, Codex, Cursor, Aider, Goose, Gemini, 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	none

See platform support for more details.

Greywall can also be used as a Go package.

Documentation

• Documentation Index
• 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.