Mathieu Virbel
3dd772d35a
Learning mode (--learning) traces filesystem access with strace and generates minimal sandbox config templates. A background monitor kills strace when the main command exits so long-lived child processes (LSP servers, file watchers) don't cause hangs. Other changes: - Add 'greywall templates list/show' subcommand - Add --template flag to load specific learned templates - Fix DNS relay: use TCP DNS (options use-vc) instead of broken UDP relay through tun2socks - Filter O_DIRECTORY opens from learned read paths - Add docs/experience.md with development notes
Greywall Documentation
Greywall is a sandboxing tool that restricts network and filesystem access for arbitrary commands. It's most useful for running semi-trusted code (package installs, build scripts, CI jobs, unfamiliar repos) with controlled side effects.
Getting Started
- Quickstart - Install greywall and run your first sandboxed command in 5 minutes
- Why Greywall - What problem it solves (and what it doesn't)
Guides
- Concepts - Mental model: OS sandbox + local proxies + config
- Troubleshooting - Common failure modes and fixes
- Using Greywall with AI agents - Defense-in-depth and policy standardization
- Recipes - Common workflows (npm/pip/git/CI)
- Templates - Copy/paste templates you can start from
Reference
- README - CLI usage
- Library Usage (Go) - Using Greywall as a Go package
- Configuration - How to configure Greywall
- Architecture - How greywall works under the hood
- Security model - Threat model, guarantees, and limitations
- Linux security features - Landlock, seccomp, eBPF details and fallback behavior
- Testing - How to run tests and write new ones
- Benchmarking - Performance overhead and profiling
Examples
See examples/ for runnable demos.
Quick Reference
Common commands
# Block all network (default)
greywall <command>
# Use custom config
greywall --settings ./greywall.json <command>
# Debug mode (verbose output)
greywall -d <command>
# Monitor mode (show blocked requests)
greywall -m <command>
# Expose port for servers
greywall -p 3000 <command>
# Run shell command
greywall -c "echo hello && ls"