### Quick Start Setup

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Clone the repository, set up dependencies, and build the binary to get started quickly.

```bash
git clone https://github.com/GreyhavenHQ/greywall
cd greywall
make setup   # Install deps and lint tools
make build   # Build the binary
./greywall --help
```

--------------------------------

### Install Greywall using Go

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Install the Greywall binary using the Go toolchain. After installation, run 'greywall setup' to install and start Greyproxy.

```bash
go install github.com/GreyhavenHQ/greywall/cmd/greywall@latest
greywall setup
```

--------------------------------

### Install and Start Greyproxy

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Install the latest Greyproxy release and start it as a systemd user service. This is optional but recommended for network filtering.

```bash
# Install and start greyproxy
greywall setup
```

--------------------------------

### Install and Start Greyproxy

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Install and start the Greyproxy service, which is required by Greywall for network filtering. This command is often run after initial installation.

```bash
greywall setup
```

--------------------------------

### Build and Run Greywall

Source: https://github.com/greyhavenhq/greywall/blob/main/CLAUDE.md

Commands for setting up dependencies, building the binary, and running the application. Use `make setup` for initial dependency installation.

```bash
make setup          # install deps + lint tools (first time)
make build          # compile binary (downloads tun2socks)
make run            # build and run
./greywall --help   # CLI usage
```

--------------------------------

### Install Greywall via Go

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Install the greywall binary using `go install`. You will need to manually create the `greywatch` alias as Go install only provides the main binary.

```bash
go install github.com/GreyhavenHQ/greywall/cmd/greywall@latest
# Create the greywatch alias yourself (Go install ships a single binary):
ln -s "$(go env GOPATH)/bin/greywall" "$(go env GOPATH)/bin/greywatch"
```

--------------------------------

### Install Greywall Go Library

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Use 'go get' to add the Greywall library to your project dependencies.

```bash
go get github.com/GreyhavenHQ/greywall
```

--------------------------------

### Install Greywall using Mise

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Manage Greywall and Greyproxy installations using the 'mise' tool.

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

--------------------------------

### Installing Bubblewrap and Socat on Linux

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Install necessary sandboxing tools for greywall on Debian-based systems.

```bash
sudo apt install bubblewrap socat
```

--------------------------------

### Quick Start: Learning Mode Workflow

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/learning-mode.md

A three-step process to enable learning mode, review the generated profile, and then run the command normally.

```bash
greywall --learning -- opencode
greywall profiles show opencode
greywall -- opencode
```

--------------------------------

### Troubleshoot Go Install Path

Source: https://github.com/greyhavenhq/greywall/blob/main/CONTRIBUTING.md

Provides instructions on how to add the Go binary directory to your PATH if the 'command not found' error occurs after 'go install'.

```bash
# Add $GOPATH/bin to your PATH
# Or use 'go env GOPATH' to find the path
```

--------------------------------

### Install Greywall from Source

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Clone the Greywall repository and build it from source using make commands.

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

--------------------------------

### Install Benchmarking Tools

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/benchmarking.md

Installs hyperfine for CLI benchmarking and benchstat for Go microbenchmark analysis. Use brew on macOS or apt on Linux for hyperfine.

```bash
# Install dependencies
brew install hyperfine   # macOS
# apt install hyperfine  # Linux

go install golang.org/x/perf/cmd/benchstat@latest
```

--------------------------------

### First-Time Setup Workflow for a New Tool

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/learning-mode.md

A typical workflow for setting up a new tool involves learning its filesystem access, reviewing the generated profile, and editing it if necessary.

```bash
# 1. Learn what the tool needs
greywall --learning -- opencode

# 2. Review the generated profile
greywall profiles show opencode

# 3. Edit if needed
greywall profiles edit opencode
```

--------------------------------

### Initialize() error

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Sets up the sandbox infrastructure, including starting HTTP and SOCKS proxies. Can be called automatically by WrapCommand.

```APIDOC
## Initialize() error

### Description
Sets up sandbox infrastructure (starts HTTP and SOCKS proxies). Called automatically by `WrapCommand` if not already initialized.

### Returns
- `error`: An error if initialization fails.
```

--------------------------------

### Install xdg-dbus-proxy on Fedora

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Install the `xdg-dbus-proxy` utility on Fedora systems to enable `notify-send` functionality within the sandbox.

```bash
# Fedora
sudo dnf install xdg-dbus-proxy
```

--------------------------------

### Install xdg-dbus-proxy on Ubuntu/Debian

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Install the `xdg-dbus-proxy` utility on Ubuntu or Debian-based systems to enable `notify-send` functionality within the sandbox.

```bash
# Ubuntu/Debian
sudo apt install xdg-dbus-proxy
```

--------------------------------

### Command Configuration Example

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/configuration.md

An example of the 'command' section in Greywall configuration, specifying commands to deny and a specific command to allow, overriding the general deny rule.

```json
{
  "command": {
    "deny": ["git push", "npm publish"],
    "allow": ["git push origin docs"]
  }
}
```

--------------------------------

### Install Bubblewrap and Socat on Linux

Source: https://github.com/greyhavenhq/greywall/blob/main/CONTRIBUTING.md

Installs necessary dependencies for testing on Linux environments, specifically for bubblewrap and socat.

```bash
sudo apt install bubblewrap socat xdg-dbus-proxy
```

--------------------------------

### Example Greywall Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/configuration.md

A comprehensive example of a Greywall configuration file, demonstrating settings for network proxy, DNS, filesystem access control, command restrictions, and SSH host/command allowances.

```json
{
  "network": {
    "proxyUrl": "socks5://localhost:43052",
    "dnsAddr": "localhost:43053"
  },
  "filesystem": {
    "denyRead": ["/etc/passwd"],
    "allowWrite": [".", "/tmp"],
    "denyWrite": [".git/hooks"]
  },
  "command": {
    "deny": ["git push", "npm publish"]
  },
  "ssh": {
    "allowedHosts": ["*.example.com"],
    "allowedCommands": ["ls", "cat", "grep", "tail", "head"]
  }
}
```

--------------------------------

### Install Greywall via Linux/Mac Script

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Install Greywall on Linux or macOS by downloading and executing an installation script. This script handles downloading, verification, and setup.

```bash
curl -fsSL https://raw.githubusercontent.com/GreyhavenHQ/greywall/main/install.sh | sh
```

--------------------------------

### Example Integration Test in Go

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/testing.md

Demonstrates a typical integration test case in Go, verifying that writes outside a specified workspace are blocked while writes inside are allowed.

```go
func TestLinux_CustomFeature(t *testing.T) {
    skipIfAlreadySandboxed(t)
    
    workspace := createTempWorkspace(t)
    cfg := testConfigWithWorkspace(workspace)
    
    // Test that writes outside workspace are blocked
    result := runUnderSandbox(t, cfg, "touch /tmp/outside.txt", workspace)
    assertBlocked(t, result)
    assertFileNotExists(t, "/tmp/outside.txt")
    
    // Test that writes inside workspace work
    insideFile := filepath.Join(workspace, "inside.txt")
    result = runUnderSandbox(t, cfg, "touch "+insideFile, workspace)
    assertAllowed(t, result)
    assertFileExists(t, insideFile)
}
```

--------------------------------

### Troubleshooting 'command not found' after go install

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Add the Go binary directory to your PATH environment variable.

```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```

--------------------------------

### Check Greywall Installation

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Verify that the greywall installation is functioning correctly. This command checks dependencies and the status of greyproxy.

```bash
greywall check
```

--------------------------------

### Install xdg-dbus-proxy on Arch Linux

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Install the `xdg-dbus-proxy` utility on Arch Linux systems to enable `notify-send` functionality within the sandbox.

```bash
# Arch
sudo pacman -S xdg-dbus-proxy
```

--------------------------------

### Install Greywall via Homebrew

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Install Greywall and its dependency Greyproxy using the Homebrew package manager on macOS.

```bash
brew tap greyhavenhq/tap
brew install greywall
```

--------------------------------

### Quick Start: Sandbox a Curl Command

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Demonstrates basic usage of the Greywall Go library to sandbox a 'curl' command. It checks platform support, creates a configuration, initializes the manager, wraps the command, and executes it.

```go
package main

import (
    "fmt"
    "os/exec"

    "github.com/GreyhavenHQ/greywall/pkg/greywall"
)

func main() {
    // Check platform support
    if !greywall.IsSupported() {
        fmt.Println("Sandboxing not supported on this platform")
        return
    }

    // Create config
    cfg := &greywall.Config{
        Network: greywall.NetworkConfig{
            AllowedDomains: []string{"api.example.com"},
        },
    }

    // Create and initialize manager
    manager := greywall.NewManager(cfg, false, false)
    defer manager.Cleanup()

    if err := manager.Initialize(); err != nil {
        panic(err)
    }

    // Wrap the command
    wrapped, err := manager.WrapCommand("curl https://api.example.com/data")
    if err != nil {
        panic(err)
    }

    // Execute it
    cmd := exec.Command("sh", "-c", wrapped)
    output, _ := cmd.CombinedOutput()
    fmt.Println(string(output))
}
```

--------------------------------

### Install Linux Dependencies

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Install necessary dependencies for Greywall on Ubuntu/Debian, Fedora, or Arch Linux.

```bash
# Ubuntu/Debian
sudo apt install bubblewrap socat xdg-dbus-proxy libsecret-tools

# Fedora
sudo dnf install bubblewrap socat xdg-dbus-proxy libsecret

# Arch
sudo pacman -S bubblewrap socat xdg-dbus-proxy libsecret
```

--------------------------------

### Learn Filesystem Access and Generate Profile

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

This command enables learning mode to trace filesystem access for a command, then automatically generates a least-privilege configuration profile. 'opencode' is used as an example.

```bash
# Learn what filesystem access a command needs, then auto-generate a profile
greywall --learning -- opencode
```

--------------------------------

### Example: Connecting to Host Postgres (macOS)

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/concepts.md

On macOS, connecting to a host's localhost service like Postgres might only require allowing localhost outbound in the configuration.

```bash
greywall -- psql -h localhost
```

--------------------------------

### Example: Connecting to Host Postgres (Linux)

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/concepts.md

On Linux, to connect to a host's localhost service, the specific port must be explicitly forwarded using the -f flag.

```bash
greywall -f 5432 -- psql -h localhost
```

--------------------------------

### Install Socat

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

If socat is not available, it can be installed using your system's package manager. This is a prerequisite for running Greywall on Linux.

```bash
apt install socat
```

```bash
dnf install socat
```

--------------------------------

### Install Bubblewrap

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

If bubblewrap is not available, it can be installed using your system's package manager. This is a prerequisite for running Greywall on Linux.

```bash
apt install bubblewrap
```

```bash
dnf install bubblewrap
```

--------------------------------

### Linux Sandbox Network Setup

Source: https://github.com/greyhavenhq/greywall/blob/main/ARCHITECTURE.md

The Linux implementation uses bubblewrap with network namespace isolation and transparent SOCKS5 proxying via tun2socks and socat bridges. This diagram illustrates the components involved.

```Go
bwrap --unshare-net
```

--------------------------------

### Run CLI Benchmarks

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/benchmarking.md

Executes the full suite of CLI benchmarks for Greywall. This measures real-world agent cost, including proxy startup and sandbox setup.

```bash
# Full benchmark suite
./scripts/benchmark.sh

# Quick mode (fewer runs)
./scripts/benchmark.sh -q

# Custom output directory
./scripts/benchmark.sh -o ./my-results

# Include network benchmarks (requires local server)
./scripts/benchmark.sh --network
```

--------------------------------

### Install uidmap on Debian/Ubuntu

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Install the 'uidmap' package, which is necessary for bwrap to create user namespaces. This is a common fix for 'bwrap: setting up uid map: Permission denied' errors.

```bash
# Install uidmap
sudo apt install uidmap  # Debian/Ubuntu
```

--------------------------------

### Install Greywall Dependencies on Fedora/RHEL

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

Installs required packages such as bubblewrap, socat, and xdg-dbus-proxy for Greywall on Fedora or RHEL systems.

```bash
sudo dnf install bubblewrap socat xdg-dbus-proxy
```

--------------------------------

### Initialize Sandbox Manager

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Initializes the Greywall sandbox manager, which includes starting necessary proxy services. It's recommended to defer the Cleanup method to release resources when done.

```go
manager := greywall.NewManager(cfg, false, false)
deffer manager.Cleanup()

if err := manager.Initialize(); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Example Learned Profile Template

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/learning-mode.md

A sample JSONC template generated by learning mode, showing `allowRead`, `allowWrite`, `denyWrite`, and `denyRead` sections. Sensitive paths are automatically denied.

```jsonc
// Learned template for "opencode"
// Generated by: greywall --learning -- opencode
// Review and adjust paths as needed
{
  "filesystem": {
    "allowRead": [
      "~/.cache/opencode",
      "~/.config/opencode"
    ],
    "allowWrite": [
      ".",
      "~/.cache/opencode",
      "~/.local/state/opencode"
    ],
    "denyWrite": [
      "~/.bashrc",
      "~/.bash_profile",
      "~/.zshrc",
      "~/.profile"
    ],
    "denyRead": [
      "~/.ssh/id_*",
      "~/.gnupg/**",
      ".env",
      ".env.*"
    ]
  }
}
```

--------------------------------

### Sandbox a Command

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Use this to sandbox a command with default network and filesystem restrictions. The `curl` command is used here as an example.

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

--------------------------------

### Run First Sandboxed Command

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Execute a command within the Greywall sandbox. This example uses curl to fetch a URL, which will fail if Greyproxy is not running.

```bash
# This will fail if no proxy is running
greywall curl https://example.com
```

--------------------------------

### Show Greywall Version

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Display the currently installed version of Greywall. This is useful for checking compatibility or reporting issues.

```bash
greywall --version
```

--------------------------------

### Check Greyproxy Status

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Verify that the greyproxy service is running and accessible. Use this after running 'greywall setup' to confirm the proxy is operational.

```bash
greywall check    # verify status
```

--------------------------------

### Observe Agent Behavior

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Run an agent in observability mode to see its actions without any restrictions. All network traffic is allowed and logged by greyproxy. 'claude' is used as an example.

```bash
# Observe what an agent does without blocking anything (allow-by-default)
greywatch -- claude
```

--------------------------------

### Create Default Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Obtain a default Greywall configuration. This configuration typically blocks all network access and enables deny-by-default filesystem reads. You can then modify it, for example, to allow specific domains.

```go
cfg := greywall.DefaultConfig()
cfg.Network.AllowedDomains = []string{"example.com"}
```

--------------------------------

### Learn Filesystem Access and Run Normally

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/cli-reference.md

First, learn filesystem access patterns with `--learning`, then run the command normally to apply the learned profile.

```bash
greywall --learning -- cargo build
```

```bash
greywall -- cargo build          # auto-loads learned profile
```

--------------------------------

### Company-Specific AI Agent Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/templates.md

Create a company-specific configuration by extending the 'code' template. This example protects sensitive directories from being read and denies specific publishing commands.

```json
{
  "extends": "code",
  "filesystem": {
    "denyRead": ["~/.company-secrets/**"]
  },
  "command": {
    "deny": ["npm publish"]
  }
}
```

--------------------------------

### Extend Another Config File with Command Restrictions

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/templates.md

Extend a local configuration file by providing its path in the 'extends' field. This example restricts 'git push' commands while inheriting settings from the specified base config.

```json
{
  "extends": "./shared/base-config.json",
  "command": {
    "deny": ["git push"]
  }
}
```

--------------------------------

### Build Binary with Version Info

Source: https://github.com/greyhavenhq/greywall/blob/main/CONTRIBUTING.md

Builds the greywall binary including version information, mimicking the build process used in CI.

```bash
make build-ci
```

--------------------------------

### Load and Extend Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Loads a configuration from a default path, provides a fallback to default settings if loading fails, and appends a new command to the deny list.

```go
cfg, err := greywall.LoadConfig(greywall.DefaultConfigPath())
if err != nil {
    log.Fatal(err)
}
if cfg == nil {
    cfg = greywall.DefaultConfig()
}

// Add additional restrictions
cfg.Command.Deny = append(cfg.Command.Deny, "dangerous-cmd")
```

--------------------------------

### Run in learning mode

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Executes a command in learning mode, tracing filesystem access via strace to automatically generate a configuration profile.

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

--------------------------------

### Install Greywall Dependencies on Alpine Linux

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

Installs required packages like bubblewrap, socat, and xdg-dbus-proxy for Greywall on Alpine Linux.

```bash
sudo apk add bubblewrap socat xdg-dbus-proxy
```

--------------------------------

### Install Greywall Dependencies on Arch Linux

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

Installs essential packages including bubblewrap, socat, and xdg-dbus-proxy for Greywall on Arch Linux.

```bash
sudo pacman -S bubblewrap socat xdg-dbus-proxy
```

--------------------------------

### Build Binary for Current Platform

Source: https://github.com/greyhavenhq/greywall/blob/main/CONTRIBUTING.md

Builds the greywall binary for the platform the command is being run on.

```bash
make build
```

--------------------------------

### Check for bwrap Binary

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/faq.md

If 'bwrap' is not found on your system after installing bubblewrap, use this command to locate it. If it's installed but not on your PATH, you may need to add its directory.

```bash
which bwrap
```

--------------------------------

### Cross-Platform Go Benchmark Comparison

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/benchmarking.md

Compares Go microbenchmark results between macOS and Linux. Run benchmarks on each platform and then use benchstat to analyze the differences.

```bash
# On macOS
go test -run=^$ -bench=. -count=10 ./internal/sandbox/... > bench_macos.txt

# On Linux
go test -run=^$ -bench=. -count=10 ./internal/sandbox/... > bench_linux.txt

# Compare
benchstat bench_macos.txt bench_linux.txt
```

--------------------------------

### Learn Filesystem Access for a Command

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Trace the filesystem access a command requires and automatically generate a configuration profile. This is useful for understanding and defining sandbox rules.

```bash
greywall --learning -- opencode
```

--------------------------------

### Greywall Execution Flow

Source: https://github.com/greyhavenhq/greywall/blob/main/ARCHITECTURE.md

This flowchart details the step-by-step execution process of Greywall, from parsing arguments and loading configuration to initializing the manager, wrapping commands, and performing cleanup.

```Go
Manager.Initialize()
```

```Go
Manager.WrapCommand()
```

```Go
Manager.Cleanup()
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Run Greywall with debug logging enabled to get detailed information about its operations. This is helpful for troubleshooting.

```bash
greywall -d -- curl https://example.com
```

--------------------------------

### Allow Local Binding and Expose Inbound Ports

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Enable a server running inside the sandbox to accept incoming connections. Requires setting `network.allowLocalBinding` to true and exposing ports using the `-p` flag.

```bash
# Example command to expose a port (actual command depends on the application)
# greywall -p <port> -- your_server_command
```

--------------------------------

### Enable Learning Mode for Filesystem Access Tracing

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/faq.md

Run Greywall in learning mode to trace filesystem access and generate a config template.

```bash
greywall --learning -- your-command
```

--------------------------------

### Running All Tests

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Execute all project tests using the make target or directly with go test.

```bash
make test

go test -v ./...
```

--------------------------------

### Expose Multiple Ports

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/cli-reference.md

Exposes multiple ports for sandboxed servers, enabling external access to several services. Used here to start a build process.

```bash
greywall -p 3000 -p 8080 -c "make start"
```

--------------------------------

### Sandbox AI Agent with Profile

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

This command sandboxes an AI coding agent using a pre-defined built-in profile. 'claude' is used as an example agent.

```bash
# Sandbox an AI coding agent with a built-in profile
greywall -- claude
```

--------------------------------

### Run All Tests

Source: https://github.com/greyhavenhq/greywall/blob/main/CONTRIBUTING.md

Execute all tests in the project using the make command. This is a standard way to ensure code quality.

```bash
make test
```

--------------------------------

### Building for Linux Distribution

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Build the greywall binary specifically for the Linux platform.

```bash
make build-linux
```

--------------------------------

### Add bwrap to PATH

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/faq.md

If the 'bwrap' binary is installed but not found, add its directory to your PATH environment variable. This command is typically used for systems where 'bwrap' is not in the default PATH.

```bash
export PATH="/usr/sbin:$PATH"
```

--------------------------------

### Run Go Microbenchmarks

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/benchmarking.md

Executes Go microbenchmarks to measure component-level overhead within the sandbox. Use -benchmem to include memory allocations.

```bash
# Run all benchmarks
go test -run=^$ -bench=. -benchmem ./internal/sandbox/...

# Run specific benchmark
go test -run=^$ -bench=BenchmarkWarmSandbox -benchmem ./internal/sandbox/...

# Multiple runs for statistical analysis
go test -run=^$ -bench=. -benchmem -count=10 ./internal/sandbox/... > bench.txt
benchstat bench.txt
```

--------------------------------

### CPU Profiling with Go Tool

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/benchmarking.md

Profile the CPU usage of the BenchmarkWarmSandbox test. This helps identify performance bottlenecks. Requires the Go toolchain.

```bash
# CPU profile
go test -run=^$ -bench=BenchmarkWarmSandbox -cpuprofile=cpu.out ./internal/sandbox/...
go tool pprof -http=:8080 cpu.out
```

--------------------------------

### Load Configuration from File

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Load Greywall configuration from a JSON file, which supports comments (JSONC). If the configuration file does not exist, it falls back to a default configuration.

```go
cfg, err := greywall.LoadConfig(greywall.DefaultConfigPath())
if err != nil {
    log.Fatal(err)
}
if cfg == nil {
    cfg = greywall.DefaultConfig() // File doesn't exist
}
```

--------------------------------

### API-Only Agent Filesystem Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/agents.md

This JSON configuration restricts write access to the current directory for an API-only agent. It's a basic example for sandboxing agent operations.

```json
{
  "filesystem": {
    "allowWrite": ["."]
  }
}
```

--------------------------------

### Run with learned profile

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Executes a command after a profile has been learned, automatically loading the generated configuration.

```bash
# Next run auto-loads the learned profile
greywall -- opencode
```

--------------------------------

### Running Greywall Command Manually

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/testing.md

Demonstrates how to manually run the Greywall executable with specific commands and optional settings files for debugging.

```bash
# Replicate what the test does
./greywall -c "the-command-that-failed"

# With a settings file
./greywall -s /path/to/settings.json -c "command"
```

--------------------------------

### Build Greywall from Source

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Build Greywall from its source code. This process clones the repository, sets up dependencies, and compiles both the `greywall` binary and the `greywatch` symlink.

```bash
git clone https://github.com/GreyhavenHQ/greywall
cd greywall
make setup && make build   # creates ./greywall and ./greywatch symlink
```

--------------------------------

### Trigger Benchmark Workflow via gh CLI

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/benchmarking.md

Manually trigger the benchmark workflow in GitHub Actions using the gh CLI. Ensure you have the gh CLI installed and authenticated.

```bash
gh workflow run benchmark.yml
```

--------------------------------

### Check Platform Support

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Verify if the current operating system supports Greywall sandboxing. This function returns true for macOS and Linux.

```go
if !greywall.IsSupported() {
    log.Fatal("Platform not supported")
}
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Common make targets for building, running, testing, and maintaining the project.

```bash
make build
make run
make test
make test-ci
make deps
make fmt
make lint
make build-ci
make help
```

--------------------------------

### Run with shell expansion

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Allows shell expansion for commands within the sandbox.

```bash
# Run with shell expansion
greywall -c "echo hello && ls"
```

--------------------------------

### macOS Sandbox Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/ARCHITECTURE.md

Seatbelt profiles are dynamically generated based on configuration to control sandbox permissions. This example shows basic profile rules for network, file, and process access.

```Go
(deny default)
(allow network-outbound (remote ip "localhost:*"))
(allow file-read* ...)
(allow process-fork), (allow process-exec)
```

--------------------------------

### Block Dangerous Commands

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Use Greywall to block specific dangerous commands. This example shows how a command like 'rm -rf /' would be blocked by default command deny rules.

```bash
greywall -c "rm -rf /"  # → blocked by command deny rules
```

--------------------------------

### Integration Test Helpers in Go

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/testing.md

Provides essential Go functions for writing sandbox integration tests, including skipping tests, running commands under a sandbox, and performing assertions on results and files.

```go
skipIfAlreadySandboxed(t)              // Skip if running inside Greywall
skipIfCommandNotFound(t, "python3")    // Skip if command missing

// Run a command under the sandbox
result := runUnderSandbox(t, cfg, "touch /etc/test", workspace)

// Assertions
assertBlocked(t, result)      // Command should have failed
assertAllowed(t, result)      // Command should have succeeded
assertContains(t, result.Stdout, "expected")

// File assertions
assertFileExists(t, "/path/to/file")
assertFileNotExists(t, "/path/to/file")

// Config helpers
cfg := testConfig()                          // Basic deny-all config
cfg := testConfigWithWorkspace(workspace)    // Allow writes to workspace
cfg := testConfigWithNetwork("example.com")  // Allow domain
```

--------------------------------

### Run Greywall with Debugging Output

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/troubleshooting.md

Run a command with Greywall's debug flag to get detailed output from the proxy and sandbox. This is helpful for diagnosing complex issues where monitor mode is insufficient.

```bash
greywall -d <command>
```

--------------------------------

### IsSupported() bool

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Checks if the current platform supports sandboxing. Returns true for macOS or Linux.

```APIDOC
## IsSupported()

### Description
Returns `true` if the current platform supports sandboxing (macOS or Linux).

### Returns
- `bool`: `true` if supported, `false` otherwise.

### Example
```go
if !greywall.IsSupported() {
    log.Fatal("Platform not supported")
}
```
```

--------------------------------

### Running a Command in Learning Mode

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/learning-mode.md

Use the `--learning` flag to trace a command's filesystem access. This relaxes the sandbox to observe all operations. On macOS, the tracer requires `sudo`.

```bash
greywall --learning -- <command>
```

--------------------------------

### Extend Learned Filesystem Profile

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/learning-mode.md

Demonstrates how to extend a learned profile by adding specific deny rules. This is useful for refining the generated template.

```json
{
  "extends": "./learned/opencode.json",
  "filesystem": {
    "denyRead": ["~/sensitive-project/**"]
  }
}
```

--------------------------------

### Combine Multiple Toolchain Profiles

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Execute a command using a profile that includes an agent and multiple toolchains. This allows for complex development environments within the sandbox.

```bash
greywall --profile opencode,node,go -- opencode
```

--------------------------------

### Expose Dev Server Port

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Sets up a Greywall manager to expose a specific port for development servers and wraps a command to run.

```go
manager := greywall.NewManager(cfg, false, false)
manager.SetExposedPorts([]int{3000})
defer manager.Cleanup()

wrapped, _ := manager.WrapCommand("npm run dev")
```

--------------------------------

### Expose Ports for Server Applications

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/quickstart.md

Run a server application within the sandbox and expose a specific port to the host machine using the -p flag.

```bash
greywall -p 3000 -c "npm run dev"
```

--------------------------------

### Running Smoke Tests on Linux

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Execute smoke tests against the built binary for full coverage, including Landlock.

```bash
./scripts/smoke_test.sh
```

--------------------------------

### Running Greywall with a Settings File

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/agents.md

This bash command demonstrates how to run Greywall with a specified JSON settings file and execute an agent command. Ensure the agent command is replaced with the actual command you intend to run.

```bash
greywall --settings ./greywall.json <agent-command>
```

--------------------------------

### DefaultConfig() *Config

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Provides a default configuration with network access blocked and filesystem reads denied by default.

```APIDOC
## DefaultConfig()

### Description
Returns a default configuration with all network blocked and deny-by-default filesystem reads enabled.

### Returns
- `*Config`: A pointer to the default configuration object.

### Example
```go
cfg := greywall.DefaultConfig()
cfg.Network.AllowedDomains = []string{"example.com"}
```
```

--------------------------------

### Platform Detection Functions

Source: https://github.com/greyhavenhq/greywall/blob/main/ARCHITECTURE.md

Provides functions to detect the operating system and check if it's supported by Greywall.

```go
func Detect() Platform  // Returns MacOS, Linux, Windows, or Unknown
func IsSupported() bool // True for MacOS and Linux
```

--------------------------------

### Configure network proxy and DNS

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Sets up external network routing through a SOCKS5 proxy and specifies a DNS address.

```jsonc
{
  // 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"]
  }
}
```

--------------------------------

### Run Greywall with Sudo for Monitoring

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

Executes the greywall command with root privileges to enable monitoring features when CAP_BPF cannot be set on the binary.

```bash
sudo greywall -m <command>
```

--------------------------------

### Testing GoReleaser Configuration Locally

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Run GoReleaser in snapshot mode to test configuration without publishing artifacts.

```bash
goreleaser release --snapshot --clean
```

--------------------------------

### Extending a Local Configuration File

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/configuration.md

Shows how to extend another configuration file using a relative path. This config inherits settings from './base-config.json' and overrides command restrictions.

```json
{
  "extends": "./base-config.json",
  "command": {
    "deny": ["git push"]
  }
}
```

--------------------------------

### Apply Built-in Greywall Profiles

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/templates.md

Use the `--profile` flag to apply built-in configuration templates for common use cases. The older `-t/--template` flag is an alias but `--profile` is recommended for new scripts.

```bash
greywall --profile npm-install -- npm install
```

```bash
greywall --profile code -- claude
```

```bash
greywall --profile claude,python -- claude
```

```bash
greywall profiles list
```

--------------------------------

### Running Tests with Coverage

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Generate test coverage reports using the make test-ci command.

```bash
make test-ci
```

--------------------------------

### Apply Local Development Server Profile

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/faq.md

Use the `local-dev-server` profile to enable binding and allow local outbound connections on macOS.

```bash
greywall --profile local-dev-server -- your-command
```

--------------------------------

### Building for macOS Distribution

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Build the greywall binary specifically for the macOS platform.

```bash
make build-darwin
```

--------------------------------

### Run Unit Tests

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/testing.md

Execute all unit tests for the project. This is useful for verifying individual functions and logic in isolation.

```bash
# Run unit tests
go test ./...
```

```bash
go test ./internal/...
```

--------------------------------

### Expose Dev Server Port

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/cli-reference.md

Run a development server command and expose a specific port.

```bash
greywall -p 5173 -c "npm run dev"
```

--------------------------------

### Define Command Configuration

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Defines the structure for command-related security configurations, including commands to deny and allow, and options for using default deny lists.

```go
type CommandConfig struct {
    Deny        []string // Command patterns to block
    Allow       []string // Exceptions to deny rules
    UseDefaults *bool    // Use default deny list (true if nil)
}
```

--------------------------------

### Running Linux Integration Tests

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Execute specific integration and Linux-focused tests for the sandbox module.

```bash
go test -v -run 'TestIntegration|TestLinux' ./internal/sandbox/...
```

--------------------------------

### Run Integration Tests

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/testing.md

Execute integration tests to verify sandbox behavior. These tests spawn real processes and check outcomes. Platform-appropriate tests run automatically.

```bash
# Run integration tests
go test -v -run 'TestIntegration|TestLinux|TestMacOS' ./internal/sandbox/...
```

```bash
# Linux-specific only
go test -v -run 'TestLinux' ./internal/sandbox/...
```

```bash
# macOS-specific only
go test -v -run 'TestMacOS' ./internal/sandbox/...
```

```bash
# With verbose output and fresh runs
go test -v -count=1 ./internal/sandbox/...
```

--------------------------------

### List Available and Saved Profiles

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/index.md

Display a list of all available built-in agent and toolchain profiles, as well as any custom profiles that have been saved.

```bash
greywall profiles list
```

--------------------------------

### Run with all network blocked

Source: https://github.com/greyhavenhq/greywall/blob/main/README.md

Executes a command with all network access blocked by default.

```bash
# Run with all network blocked (default)
greywall -- curl https://example.com
```

--------------------------------

### Cleanup()

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/library.md

Stops proxies and releases all sandbox resources. Should be called using `defer`.

```APIDOC
## Cleanup()

### Description
Stops proxies and releases resources. Always call via `defer`.
```

--------------------------------

### Go Test Coverage Reporting

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/testing.md

Commands to generate and view test coverage reports for Go projects. Use `-coverprofile` to create a coverage file and `go tool cover` to process it.

```bash
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out  # View in browser
go tool cover -func=coverage.out  # Summary
```

--------------------------------

### Environment Sanitization

Source: https://github.com/greyhavenhq/greywall/blob/main/ARCHITECTURE.md

Illustrates the environment variables that are stripped by Greywall to prevent library injection attacks.

```go
# Linux: LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, etc.
# macOS: DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, etc.
```

--------------------------------

### Check Linux Security Features

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/linux-security-features.md

Run this command to see which security features are detected and available on your system. The output provides details on kernel version, specific feature support, and overall feature status.

```bash
# Check what features are available on your system
greywall --linux-features
```

--------------------------------

### Lint and Format Greywall Code

Source: https://github.com/greyhavenhq/greywall/blob/main/CLAUDE.md

Commands for formatting code with `gofumpt` and linting with `golangci-lint`. Always run these before committing.

```bash
make fmt            # format with gofumpt
make lint           # golangci-lint (staticcheck, errcheck, gosec, govet, revive, gofumpt, misspell, etc.)
```

--------------------------------

### Testing with Proxy Configuration on macOS

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/contributing.md

Configure and test greywall with a SOCKS5 proxy URL.

```bash
echo '{"network":{"proxyUrl":"socks5://localhost:43052"}}' > /tmp/test.json
./greywall -s /tmp/test.json curl https://example.com
```

--------------------------------

### Extending an Absolute Path Configuration File

Source: https://github.com/greyhavenhq/greywall/blob/main/docs/configuration.md

Illustrates extending a configuration file using an absolute path. This config inherits settings from '/etc/greywall/company-base.json' and specifies denied read paths.

```json
{
  "extends": "/etc/greywall/company-base.json",
  "filesystem": {
    "denyRead": ["~/company-secrets/**"]
  }
}
```