Greywall Agent Sandbox
Limit what coding agents can access across files, networks, and system calls.
- Source repo
- GreyhavenHQ/greywall
- Stars
- ★ 311
- Last updated
- 6d ago
- License
- Apache-2.0
- Primary language
- Go
- FA score
- 80/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers running Claude Code, Codex, or Cursor locally who want to restrict access to SSH keys and files outside the working directory.
- Not a fit if
- Teams that require full transparent network and DNS capture on macOS
- Source review
- 80/100 · Good
What does this agent do, and when should you use it?
Greywall is a local command-line sandbox for running AI coding agents and other commands on Linux and macOS without containers. Its greywall mode denies access by default across files, network connections, and system calls; greywatch provides allow-by-default observation and logs network requests to the GreyProxy dashboard. Linux uses mechanisms including bubblewrap, Landlock, Seccomp BPF, eBPF monitoring, and TUN-based network capture, while macOS uses Seatbelt. Built-in profiles, JSON settings, and CLI options let users control access, and learning mode traces filesystem access to generate a profile. Greywall is delivered as a local CLI and is also usable as a Go package.
Run a command with greywall -- <command> and Greywall applies the selected rules to filesystem access, network connections, and system calls; configured dangerous commands can also be blocked. Built-in profiles grant access for tools such as Claude Code, Codex, and Cursor, as well as language toolchains; --profile combines profiles, while --allow-path and --allow-read-path grant paths for one run. Network connections route through GreyProxy. In greywatch or --watch mode, network requests are allowed and logged, and filesystem policy is permissive. --learning traces filesystem access and generates a least-privilege profile; -m monitors sandbox violations. Settings are read from ~/.config/greywall/greywall.json by default, or the macOS Application Support directory.
- Developers running Claude Code, Codex, or Cursor locally who want to restrict access to SSH keys and files outside the working directory.
- Engineers who want to see which files and network destinations a coding agent uses before setting restrictions can run
greywatchand inspect the GreyProxy dashboard. - Teams that need separate access rules for an agent and its language toolchain can combine built-in agent and toolchain profiles.
- Developers who want to derive least-privilege settings from observed filesystem access can trace a command with
--learning. - Engineering teams that need local command isolation on Linux or macOS without relying on Docker.
How do you install or deploy this agent?
On macOS, install with Homebrew; the install script is documented for Linux and Mac. Linux requires bubblewrap and socat; xdg-dbus-proxy and libsecret-tools are optional. Homebrew and the install script install GreyProxy as a dependency; the README also identifies GreyProxy as the network proxy component for other installation paths. Run greywall check to inspect dependencies and status.
brew tap greyhavenhq/tap
brew install greywallcurl -fsSL https://raw.githubusercontent.com/GreyhavenHQ/greywall/main/install.sh | shgreywall checkHow do you use this agent?
Run a restricted command with greywall -- <command>. Use a profile or learning mode to adjust access. These examples start Claude, observe its behavior, and trace OpenCode filesystem access.
greywall -- claude
greywatch -- claude
greywall --learning -- opencodeCombine agent and toolchain profiles with --profile, and store additional settings in a JSON configuration file.
greywall --profile claude,python -- claude{
"network": {
"proxyUrl": "socks5://localhost:1080",
"dnsAddr": "localhost:5353"
},
"filesystem": {
"defaultDenyRead": true,
"allowRead": ["~/.config/myapp"],
"allowWrite": ["."],
"denyWrite": ["~/.ssh/**"],
"denyRead": ["~/.ssh/id_*", ".env"]
},
"command": {
"deny": ["git push", "npm publish"]
}
}What are this agent's strengths and limitations?
- Linux combines bubblewrap, Landlock, Seccomp BPF, eBPF, and TUN capture for layered isolation.
- Default-deny filesystem and network controls come with built-in agent profiles and per-run path grants.
greywatchand--learninglet teams observe behavior before generating and tightening policies.- Supports Linux and macOS without requiring containers.
- Linux installation requires bubblewrap and socat; network proxying also depends on GreyProxy.
- macOS lacks full transparent network and DNS capture, and learning mode requires sudo.
- Network isolation and transparent capture on Linux depend on TUN; isolation mechanisms and available features vary by platform.
- The README does not describe commercial support, service levels, or a hosted service, so teams must install and maintain the local tools.
How does this agent compare with similar options?
The README presents Greywall as a container-free sandbox and greywatch as the observability counterpart to deny-by-default mode. It identifies Greywall as a fork of Fence and says Anthropic's sandbox-runtime was an inspiration; it provides no feature or performance comparison data.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Greywall Agent Sandbox This agent | 80 · Good | CLIFree | ★ 311 | 6d ago | Go | Codex · Claude Code |
| NVIDIA NemoClaw | 65 · Some gaps | CLIFree + model costs | ★ 23k | today | TypeScript | — |
| h5i — A Security-First Headless Browser for AI Agents | 84 · Good | CLIFree | ★ 805 | today | Rust | Codex · Claude Code |
| Node9 | 82 · Good | CLIFreemium | ★ 219 | 3d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Deny-by-default policies, configurable path and command rules, layered Linux isolation, and macOS Seatbelt support least privilege. Startup presents profile permissions and offers edit or skip choices. The docs describe proxy traffic routing, credential substitution, D-Bus isolation, and the consequences of exposing SSH/GPG sockets; Apache licensing and fork attribution are stated. Dependency security is thin: a dependency list is provided, but no vulnerability review or pinning policy is shown. Setup downloads and starts a proxy, and the install script is piped to a shell with checksum verification described, but side effects and recovery steps are not fully covered.
The README, configuration guide, and security model mostly agree on restrictive defaults and the proxy's role, and document reduced isolation in containers or when TUN is unavailable. Linux security documentation also describes the effects of missing kernel features. Go modules are versioned and platform installation guidance is present, but the external proxy and system tools depend on the host environment. Check, monitor, debug, and FAQ guidance helps diagnose failures, though coverage of failure and recovery cases is incomplete.
The project clearly targets semi-trusted commands, AI coding agents, build scripts, and CI, and states where its threat model does not apply. Configuration, proxy, port forwarding, learning, and watch modes provide concrete capability boundaries and invocation choices. Linux and macOS support is detailed, but Windows is unsupported and Linux network isolation in containers can be reduced by permission limits.
Documentation is organized across quickstart, configuration, security model, platform and Linux feature guides, and FAQ; installation covers multiple methods and Linux dependencies. Examples are plentiful, limitations are specific, and Apache-2.0 is clear. The relationship among the greywatch alias, greywall --watch, and greyproxy is explained but somewhat involved. Version tags and a release entry point are described, but the supplied material has no changelog. Security contact and disclosure timeline are given, while maintainer identity remains limited.
The product combines filesystem, network, and syscall restrictions with learning, monitoring, and a proxy dashboard, producing path clues and network visibility that can inform tighter policies. Learning mode and built-in agent/toolchain profiles reduce manual policy work. Value depends on proxy setup, platform differences, and available permissions; watch mode relaxes default network and filesystem restrictions, so users must choose the mode deliberately.
Security claims are explained across the README, security model, Linux feature guide, configuration reference, and FAQ, making concrete boundaries and fallback conditions traceable. The materials corroborate one another, though they are primarily claims from the same repository and do not provide independent validation. The docs generally distinguish behavior, dependencies, and limitations, and explicitly say the product is not designed to contain determined escape attempts. This review did not execute the project.
- Greywall is explicitly defense-in-depth for semi-trusted code, not a strong boundary against actively malicious escape attempts.
- Watch mode allows network access and relaxes filesystem restrictions by default; in Linux containers or without TUN, programs that ignore proxy environment variables may bypass network restrictions.
- Exposing SSH/GPG agent sockets or audio/video related sockets expands access to identity or devices; enable them only when needed and understand the consequences.
FAQ
Are my files allowed by default?
greywall restricts access by default, generally leaving only the working directory accessible. Built-in profiles and --allow-path or --allow-read-path can grant more access. The README says mandatory deny rules also remain in watch mode.Do network requests connect directly to the internet?
greywatch allows and logs requests. Linux supports TUN-based transparent capture, while macOS does not support full transparent capture or DNS capture.Can I observe an agent before enforcing restrictions?
greywatch -- <command> or greywall --watch -- <command> to observe in a mode that allows network requests and logs them in the GreyProxy dashboard.