Greywall

The sandboxing layer of the GreyHaven platform.

Greywall wraps commands in a sandbox that blocks network access by default and restricts filesystem operations. On Linux, it uses tun2socks for truly transparent proxying: all TCP/UDP traffic is captured at the kernel level via a TUN device and forwarded through an external SOCKS5 proxy. No application awareness needed.

# Block all network access (default — no proxy running = no connectivity)
greywall -- curl https://example.com

# Route traffic through an external SOCKS5 proxy
greywall --proxy socks5://localhost:1080 -- curl https://example.com

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

Greywall also works as a permission manager for CLI agents. See agents.md for integration with Claude Code, Codex, Gemini CLI, OpenCode, and others.

Install

macOS / Linux:

curl -fsSL https://gitea.app.monadical.io/monadical/greywall/raw/branch/main/install.sh | sh

Other installation methods

Go install:

go install gitea.app.monadical.io/monadical/greywall/cmd/greywall@latest

Build from source:

git clone https://gitea.app.monadical.io/monadical/greywall
cd greywall
make setup && make build

Linux dependencies:

• bubblewrap — container-free sandboxing (required)
• socat — network bridging (required)

Check dependency status with greywall --version.

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 and dependency status
greywall --version

Learning mode

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

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

# List generated templates
greywall templates list

# Show a template's content
greywall templates show opencode

# Next run auto-loads the learned template
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.

Features

• Transparent proxy — All TCP/UDP traffic captured at the kernel level via tun2socks and routed through an external SOCKS5 proxy (Linux)
• Network isolation — All outbound blocked by default; traffic only flows when a proxy is available
• Filesystem restrictions — Deny-by-default read mode, controlled write paths, sensitive file protection
• Learning mode — Trace filesystem access with strace and auto-generate config templates
• Command blocking — Deny dangerous commands (rm -rf /, git push, shutdown, etc.)
• SSH filtering — Control which hosts and commands are allowed over SSH
• Environment hardening — Strips dangerous env vars (LD_PRELOAD, DYLD_*, etc.)
• Violation monitoring — Real-time logging of sandbox violations (-m)
• Shell completions — greywall completion bash|zsh|fish|powershell
• Cross-platform — Linux (bubblewrap + seccomp + Landlock + eBPF) and macOS (sandbox-exec)

Greywall can also be used as a Go package.

Documentation

• Documentation Index
• Quickstart Guide
• Why Greywall
• Configuration Reference
• Security Model
• Architecture
• Linux Security Features
• AI Agent Integration
• Library Usage (Go)
• Troubleshooting

Attribution

Greywall is based on Fence by Use-Tusk.

Inspired by Anthropic's sandbox-runtime.