Greywall and Greyproxy

https://docs.greywall.io/
Admin
Greywall and Greyproxy are sandbox and proxy tools for sovereign AI that provide deny-by-default OS...
Tokens:34,105
Snippets:526
Trust Score:5.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install and Start Greyproxy

Source: https://docs.greywall.io/greywall/quickstart

Installs the recommended Greyproxy companion, which provides SOCKS5 proxying and a dashboard. It also starts a systemd user service for Greyproxy.

```bash
# Install and start greyproxy  
greywall setup  

```

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

### Install and Start Greyproxy via Greywall

Source: https://docs.greywall.io/greyproxy/quickstart

If you are using Greywall, this command automates the installation and startup of greyproxy.

```bash
greywall setup
```

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

### Common Usage Examples

Source: https://docs.greywall.io/greyproxy/cli-reference

A collection of common tasks including starting the server, installing the service, and viewing logs.

```bash
# Start in foreground with default config
greyproxy serve

# Start with a custom config file
greyproxy serve -C ~/my-greyproxy.yml

# Install as a service (starts automatically on login)
greyproxy install

# Check service status
greyproxy service status

# View logs (Linux systemd)
journalctl --user -u greyproxy -f

# View logs (macOS)
tail -f ~/Library/Logs/greyproxy.log
```

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

### Install and Check Greywall Proxy

Source: https://docs.greywall.io/greywall/troubleshooting

Use these commands to install and start the greyproxy service, and then verify its status. This is a solution for 'Connection refused' errors.

```bash
greywall setup    # install and start greyproxy  
greywall check    # verify status  

```

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

### Install Greywall Go Library

Source: https://docs.greywall.io/greywall/library

Use 'go get' to install the Greywall library. This command fetches and installs the specified package.

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

```

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

### Common Usage Examples

Source: https://docs.greywall.io/greywall/cli-reference

Various examples demonstrating sandboxing, template usage, and monitoring.

```bash
# Sandbox a single command  
greywall -- curl https://example.com  
  
# Sandbox a shell pipeline  
greywall -c "cat package.json | grep name"  
  
# Use a built-in template  
greywall -t code -- claude  
  
# Use multiple profiles  
greywall --profile claude,python -- claude  
  
# Override proxy  
greywall --proxy socks5://proxy.internal:1080 -- npm install  
  
# Monitor what gets blocked without stopping the command  
greywall -m -- pip install -r requirements.txt  
  
# Learn filesystem access, then run normally  
greywall --learning -- cargo build  
greywall -- cargo build          # auto-loads learned template  
  
# Expose dev server port  
greywall -p 5173 -c "npm run dev"  
```

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

### Install Greyproxy as a Systemd User Service

Source: https://docs.greywall.io/greyproxy/quickstart

Installs the greyproxy binary to ~/.local/bin/ and registers it as a systemd user service, starting it automatically. The dashboard will be accessible at http://localhost:43080.

```bash
./greyproxy install
```

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

### Setup and Update Workflow

Source: https://docs.greywall.io/greywall/learning-mode

Standard procedures for initial tool setup and updating existing templates after configuration changes.

```bash
# 1. Learn what the tool needs  
greywall --learning -- opencode  
  
# 2. Review the generated template  
greywall templates show opencode  
  
# 3. Edit if needed (the file path is shown by greywall)  
# e.g., remove paths you don't want to allow  
  
# 4. Run normally from now on  
greywall -- opencode  
```

```bash
# Update the template after installing new plugins  
greywall --learning -- opencode  
```

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

### Quick Start: Sandbox a Command with Greywall

Source: https://docs.greywall.io/greywall/library

This example demonstrates how to use Greywall to sandbox a 'curl' command. It checks platform support, configures network restrictions, 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))
}

```

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

### Example Integration Test in Go

Source: https://docs.greywall.io/greywall/testing

An example of a complete integration test that verifies writes outside the workspace are blocked and writes inside the workspace are allowed. It utilizes helper functions for setup and assertions.

```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)  
}  
```

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

### Usage Examples

Source: https://docs.greywall.io/greywall/cli-reference

Practical examples demonstrating common use cases for the Greywall CLI.

```APIDOC
## Examples

```
# Sandbox a single command
greywall -- curl https://example.com

# Sandbox a shell pipeline
greywall -c "cat package.json | grep name"

# Use a built-in template
greywall -t code -- claude

# Use multiple profiles
greywall --profile claude,python -- claude

# Override proxy
greywall --proxy socks5://proxy.internal:1080 -- npm install

# Monitor what gets blocked without stopping the command
greywall -m -- pip install -r requirements.txt

# Learn filesystem access, then run normally
greywall --learning -- cargo build
greywall -- cargo build          # auto-loads learned template

# Expose dev server port
greywall -p 5173 -c "npm run dev"
```
```

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

### Install Greywall using Go Install

Source: https://docs.greywall.io/greywall/quickstart

Installs the latest Greywall version directly using the Go toolchain.

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

```

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

### greyproxy install

Source: https://docs.greywall.io/greyproxy/cli-reference

Installs greyproxy as a persistent background service.

```APIDOC
## greyproxy install

### Description
Installs greyproxy as a persistent background service. It copies the binary to ~/.local/bin/greyproxy, registers a systemd user service (Linux) or launchd user agent (macOS), and starts the service immediately.

### Parameters
#### Query Parameters
- **-C** (path) - Optional - Config file path for the installed service to use.
```

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

### Setup Greywall

Source: https://docs.greywall.io/greyproxy/using-with-greywall

Run the greywall setup command to configure Greywall, which may also set up Greyproxy.

```bash
greywall setup  
```

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

### Common Python / pip Allow Rules

Source: https://docs.greywall.io/greyproxy/rules

Example rules for allowing access to PyPI repositories for package installation.

```plaintext
pypi.org             allow  
files.pythonhosted.org allow  
*.pypi.org           allow  
```

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

### Run Greyproxy in Foreground

Source: https://docs.greywall.io/greyproxy/quickstart

Starts the greyproxy server directly in the foreground without installing it as a service.

```bash
greyproxy serve
```

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

### Install Greyproxy

Source: https://docs.greywall.io/greyproxy/troubleshooting

This command is used to install Greyproxy. If the binary is not found after installation, this command should be re-run.

```bash
greyproxy install
```

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

### Quick Start Learning Mode

Source: https://docs.greywall.io/greywall/learning-mode

The standard workflow for generating and using a filesystem template for a command.

```bash
# Step 1: Run in learning mode  
greywall --learning -- opencode  
  
# Step 2: Review what was generated  
greywall templates show opencode  
  
# Step 3: Run normally — template auto-loads  
greywall -- opencode  
```

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

### Install Greywall via Script (Linux/Mac)

Source: https://docs.greywall.io/greywall

Installs Greywall by downloading and executing an installation script.

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

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

### Example Greywall Configuration

Source: https://docs.greywall.io/greywall/configuration

A comprehensive example showing network, filesystem, command, and SSH configuration blocks.

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

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

### Run `poetry install` in `greywall` Monitor Mode

Source: https://docs.greywall.io/greywall/recipes/pip-poetry

Execute `poetry install` with `greywall` in monitor mode (`-m`) to observe egress without enforcing strict policies initially. This is useful for debugging or initial setup.

```bash
greywall -m --settings ./greywall.json poetry install

```

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

### Run Greyproxy with Custom Configuration

Source: https://docs.greywall.io/greyproxy/quickstart

Starts the greyproxy server in the foreground using a specified configuration file.

```bash
greyproxy serve -C greyproxy.yml
```

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

### Serve Greyproxy with Custom Configuration

Source: https://docs.greywall.io/greyproxy/configuration

Use this command to start the Greyproxy server with a specified YAML configuration file.

```bash
greyproxy serve -C greyproxy.yml  

```

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

### Install Missing Dependencies

Source: https://docs.greywall.io/greywall/linux-security-features

Commands to install required system utilities if they are missing.

```bash
apt install bubblewrap
dnf install bubblewrap
```

```bash
apt install socat
dnf install socat
```

```bash
sudo apt install bpftrace
```

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

### Install Benchmarking Dependencies

Source: https://docs.greywall.io/greywall/benchmarking

Installs necessary tools like hyperfine for CLI benchmarks and benchstat for Go microbenchmark analysis. Use brew for macOS and apt for Linux.

```bash
# Install dependencies  
brew install hyperfine   # macOS  
# apt install hyperfine  # Linux  
  
go install golang.org/x/perf/cmd/benchstat@latest  
  
# Run CLI benchmarks  
./scripts/benchmark.sh  
  
# Run Go microbenchmarks  
go test -run=^$ -bench=. -benchmem ./internal/sandbox/...  
```

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

### Clone and Build Greywall from Source

Source: https://docs.greywall.io/greywall/quickstart

Recommended for current development. Clones the repository, builds the executable, and installs it to the system path.

```bash
git clone https://github.com/GreyhavenHQ/greywall  
cd greywall  
go build -o greywall ./cmd/greywall  
sudo mv greywall /usr/local/bin/  

```

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

### Check Installation

Source: https://docs.greywall.io/greywall/cli-reference

Verify that greywall and its required dependencies are correctly installed.

```bash
greywall check  
```

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

### greyproxy serve

Source: https://docs.greywall.io/greyproxy/cli-reference

Starts the proxy server in the foreground.

```APIDOC
## greyproxy serve

### Description
Starts the proxy server in the foreground. The server initializes all configured proxy services and the dashboard/API.

### Parameters
#### Query Parameters
- **-C** (path) - Optional - Path to a YAML config file. Defaults to the embedded default config.
```

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

### Start Proxy Server

Source: https://docs.greywall.io/greyproxy/cli-reference

Commands to launch the proxy server in the foreground, optionally specifying a configuration file.

```bash
greyproxy serve
greyproxy serve -C greyproxy.yml
```

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

### Example Greyproxy YAML Configuration

Source: https://docs.greywall.io/greyproxy/configuration

This is a comprehensive example of a greyproxy.yml file. It defines the main server address, database path, and configurations for multiple services like HTTP, SOCKS5, and DNS proxies.

```yaml
greyproxy:
  addr: ":43080"        # Dashboard and API
  db: "./greyproxy.db"  # SQLite database

services:
  - name: http-proxy
    addr: ":43051"
    handler:
      type: http
    listener:
      type: tcp

  - name: socks5-proxy
    addr: ":43052"
    handler:
      type: socks5
    listener:
      type: tcp

  - name: dns-proxy
    addr: ":43053"
    handler:
      type: dns
    listener:
      type: udp

```

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

### Install Greywall with Go

Source: https://docs.greywall.io/greywall

Installs the latest version of Greywall using the Go package manager.

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

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

### Apply Built-in Greywall Templates

Source: https://docs.greywall.io/greywall/templates

Use the -t or --template flag to apply a built-in configuration template. For example, 'npm-install' applies a template for npm installation, and 'code' wraps Claude Code.

```bash
# Use a built-in template  
greywall -t npm-install npm install  
  
# Wraps Claude Code  
greywall -t code -- claude  
  
# List available templates  
greywall --list-templates  

```

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

### Basic Greywall Commands

Source: https://docs.greywall.io/greywall

Demonstrates fundamental Greywall commands for checking installation, sandboxing, learning, and blocking.

```bash
# Check that greywall installation is ok  
greywall check  
```

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

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

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

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

### Install Greyproxy via Homebrew (macOS)

Source: https://docs.greywall.io/greyproxy/quickstart

Use this command to install Greyproxy on macOS using Homebrew. Ensure you have Homebrew installed.

```bash
brew tap greyhavenhq/tap
brew install greyproxy
```

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

### Install Bubblewrap and Socat on Linux

Source: https://docs.greywall.io/greywall/contributing

Install necessary sandboxing tools for Greywall on Debian-based Linux distributions.

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

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

### Install Greyproxy via Greywall

Source: https://docs.greywall.io/greyproxy

Installs Greyproxy as a dependency when setting up Greywall. This command assumes Greywall is already installed or being set up.

```bash
# Or install via greywall (installs greyproxy as a dependency)
greywall setup
```

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

### Install Greywall and Greyproxy

Source: https://docs.greywall.io/greyproxy/using-with-greywall

Install both Greywall and Greyproxy using Homebrew on macOS. Greywall installation includes Greyproxy as a dependency.

```bash
# macOS (Homebrew)
brew tap greyhavenhq/tap
brew install greywall   # installs greyproxy as a dependency  
```

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

### Common Go Modules Allow Rules

Source: https://docs.greywall.io/greyproxy/rules

Example rules for allowing access to Go module proxy and package repositories.

```plaintext
proxy.golang.org     allow  
sum.golang.org       allow  
*.pkg.go.dev         allow  
```

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

### Add Go Binary to PATH

Source: https://docs.greywall.io/greywall/contributing

Configure the system's PATH environment variable to include Go binaries installed via `go install`.

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

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

### Install Greywall with Homebrew (macOS)

Source: https://docs.greywall.io/greywall

Installs Greywall and its dependency Greyproxy using Homebrew on macOS.

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

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

### Verify Greywall Installation

Source: https://docs.greywall.io/greywall/quickstart

Checks the installed Greywall version and verifies system dependencies and Greyproxy status.

```bash
# Show version  
greywall --version  
  
# Check dependencies, security features, and greyproxy status  
greywall check  

```

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

### Install Greyproxy via Homebrew

Source: https://docs.greywall.io/greyproxy

Installs Greyproxy on macOS using the Homebrew package manager. Ensure you have Homebrew installed and the greyhavenhq/tap added.

```bash
# macOS via Homebrew
brew tap greyhavenhq/tap
brew install greyproxy
```

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

### Install bubblewrap and socat on Alpine Linux

Source: https://docs.greywall.io/greywall/linux-security-features

Use this command to install the necessary dependencies for greywall on Alpine Linux.

```bash
sudo apk add bubblewrap socat  

```

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

### Execute npm install with Greywall

Source: https://docs.greywall.io/greywall/recipes/npm-install

Run the npm install command through the Greywall wrapper using the specified settings file.

```bash
greywall --settings ./greywall.json npm install
```

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

### Install bubblewrap and socat on Fedora/RHEL

Source: https://docs.greywall.io/greywall/linux-security-features

Use this command to install the necessary dependencies for greywall on Fedora or RHEL-based systems.

```bash
sudo dnf install bubblewrap socat  

```

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

### Install Python Dependencies with `poetry` using `greywall`

Source: https://docs.greywall.io/greywall/recipes/pip-poetry

Use `greywall` to manage `poetry install` commands, applying egress restrictions. Point to your `greywall.json` settings file.

```bash
greywall --settings ./greywall.json poetry install

```

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

### Install bubblewrap and socat on Arch Linux

Source: https://docs.greywall.io/greywall/linux-security-features

Use this command to install the necessary dependencies for greywall on Arch Linux.

```bash
sudo pacman -S bubblewrap socat  

```

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

### Run Full CLI Benchmark Suite

Source: https://docs.greywall.io/greywall/benchmarking

Executes the complete suite of CLI benchmarks, measuring real-world agent cost including proxy startup and sandbox setup. Use options to customize runs, output, and include network benchmarks.

```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 bubblewrap and socat on Debian/Ubuntu

Source: https://docs.greywall.io/greywall/linux-security-features

Use this command to install the necessary dependencies for greywall on Debian or Ubuntu-based systems.

```bash
sudo apt install bubblewrap socat  

```

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

### Initialize Sandbox Manager

Source: https://docs.greywall.io/greywall/library

Create and initialize a Greywall sandbox manager. Ensure `Cleanup()` is called using `defer` to release resources. Initialization starts the necessary proxy services.

```go
manager := greywall.NewManager(cfg, false, false)  
defer manager.Cleanup()  
  
if err := manager.Initialize(); err != nil {  
    log.Fatal(err)  
}

```

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

### Run npm install in monitor mode

Source: https://docs.greywall.io/greywall/recipes/npm-install

Use monitor mode to identify and debug blocked network requests during the installation process.

```bash
greywall -m --settings ./greywall.json npm install
```

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

### Check Greyproxy Health and Start Service

Source: https://docs.greywall.io/greyproxy/troubleshooting

Verify the greyproxy service is running by checking its status or making a health check request to the API. If it's not running, start it using 'greyproxy service start'.

```bash
greyproxy service status  
# or  
curl http://localhost:43080/api/health  

# If not running:
greyproxy service start  
```

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

### Check Version

Source: https://docs.greywall.io/greyproxy/cli-reference

Command to display the current version of the installed Greyproxy binary.

```bash
greyproxy version
```

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

### Install Python Dependencies with `pip` using `greywall`

Source: https://docs.greywall.io/greywall/recipes/pip-poetry

Run `pip install` with `greywall` to enforce the configured egress policies. Ensure your `greywall.json` settings file is specified.

```bash
greywall --settings ./greywall.json pip install -r requirements.txt

```

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

### Install Persistent Service

Source: https://docs.greywall.io/greyproxy/cli-reference

Commands to install Greyproxy as a background service on Linux or macOS, with an optional custom configuration path.

```bash
greyproxy install
greyproxy install -C /etc/greyproxy/greyproxy.yml
```

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

### Add Go binary directory to PATH

Source: https://docs.greywall.io/greywall/faq

If you installed Greywall via 'go install' and the binary is not found, add the Go binary directory to your PATH. Add this to your shell profile for permanent access.

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

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

### Example Benchmark Output Table

Source: https://docs.greywall.io/greywall/benchmarking

Illustrates typical output from benchmark runs, showing execution times for sandboxed and unsandboxed commands, along with the calculated overhead factor.

```plaintext
Benchmark                      Unsandboxed    Sandboxed    Overhead  
true                           1.2 ms         45 ms        37.5x  
git status                     15 ms          62 ms        4.1x  
python -c 'pass'               25 ms          73 ms        2.9x  
```

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

### Common npm / Node.js Allow Rules

Source: https://docs.greywall.io/greyproxy/rules

Example rules for allowing access to npm registries and GitHub for package downloads.

```plaintext
*.npmjs.org          allow  (npm registry)
*.github.com         allow  (GitHub tarballs)
registry.yarnpkg.com allow  (Yarn)
```

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

### Basic Greywall Usage Examples

Source: https://docs.greywall.io/greywall

Illustrates various ways to use Greywall for sandboxing commands, including network blocking, shell expansion, proxy routing, port exposure, and debugging.

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

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

```bash
# Route through a SOCKS5 proxy (any proxy, not just greyproxy)  
greywall --proxy socks5://localhost:1080 -- npm install  
```

```bash
# Expose a port for inbound connections (e.g., dev servers)  
greywall -p 3000 -c "npm run dev"  
```

```bash
# Enable debug logging  
greywall -d -- curl https://example.com  
```

```bash
# Monitor sandbox violations  
greywall -m -- npm install  
```

```bash
# Show available Linux security features  
greywall --linux-features  
```

```bash
# Show version  
greywall --version  
```

```bash
# Check dependencies, security features, and greyproxy status  
greywall check  
```

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

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

### Install uidmap and Make bwrap Setuid

Source: https://docs.greywall.io/greywall/troubleshooting

These commands provide a quick fix for 'bwrap: setting up uid map: Permission denied' errors on Linux by installing the uidmap package and setting the bwrap executable to be setuid.

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

# Make bwrap setuid  
sudo chmod u+s $(which bwrap)  

```

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

### Configure Filesystem Access Restrictions

Source: https://docs.greywall.io/greywall/library

Example of initializing a Greywall configuration to restrict filesystem access. It specifies paths to allow writing to and paths to deny reading from.

```go
cfg := &greywall.Config{
    Filesystem: greywall.FilesystemConfig{
        AllowWrite: []string{".", "/tmp"},
        DenyRead:   []string{"~/.ssh", "~/.aws"},
    },
}

```

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

### Example Greywall Configuration Output

Source: https://docs.greywall.io/greywall/import-claude

This JSON object represents a potential output from the `greywall import --claude` command, showing filesystem and command permissions.

```json
{
  "extends": "code",
  "filesystem": {
    "allowWrite": [
      ".",
      "~/.cache/claude",
      "~/.config/claude",
      "~/.local/state/claude"
    ],
    "denyRead": [
      "~/.ssh/id_*",
      ".env",
      ".env.*"
    ]
  },
  "command": {
    "allow": [
      "git push origin docs"
    ],
    "deny": [
      "npm publish"
    ]
  }
}
```

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

### Subcommands

Source: https://docs.greywall.io/greywall/cli-reference

Available subcommands for managing Greywall, checking installations, and interacting with templates and profiles.

```APIDOC
## Subcommands

### `greywall check`

Check that greywall and its dependencies are correctly installed.

```
greywall check
```

Verifies:
  * Required binaries (`bwrap`, `socat` on Linux)
  * Linux kernel security features (Landlock, seccomp, eBPF)
  * Greyproxy installation and service status


### `greywall setup`

Download and install Greyproxy, then start it as a service.

```
greywall setup
```

Installs greyproxy to `~/.local/bin/greyproxy` and registers it as a systemd user service (Linux) or launchd agent (macOS).


### `greywall --linux-features`

Print the Linux kernel security features available on the current system.

```
greywall --linux-features
```

Example output:

```
Linux Sandbox Features:
  Kernel: 6.8
  Bubblewrap (bwrap): true
  Socat: true
  Seccomp: true (log level: 2)
  Landlock: true (ABI v4)
  eBPF: true (CAP_BPF: true, root: false)

Feature Status:
  ✓ Minimum requirements met (bwrap + socat)
  ✓ Landlock available for enhanced filesystem control
  ✓ Violation monitoring available
  ✓ eBPF monitoring available (enhanced visibility)
```


### `greywall --list-templates`

List all available built-in templates.

```
greywall --list-templates
```


### `greywall templates list`

List all **learned** templates (generated by `--learning` mode).

```
greywall templates list
```


### `greywall templates show <name>`

Print the content of a learned template.

```
greywall templates show opencode
```


### `greywall import --claude`

Import permissions from a Claude Code settings file and convert them to a greywall config. See Importing from Claude Code for full documentation.

```
greywall import --claude
greywall import --claude --save
greywall import --claude -f ~/.claude/settings.json --save
```


### `greywall profiles list`

List all available and saved profiles (built-in agent profiles and saved custom profiles).

```
greywall profiles list
```
```

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

### Run a Sandboxed Command (Fails without Proxy)

Source: https://docs.greywall.io/greywall/quickstart

Executes a command within a sandbox. This example will fail with a connection refused error if no SOCKS5 proxy is running, as network access is blocked by default.

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

```

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

### Configure Allowed Domains for Network Access

Source: https://docs.greywall.io/greywall/library

Example of initializing a Greywall configuration to allow access to specific network domains, including wildcards. This is useful for restricting outbound network connections.

```go
cfg := &greywall.Config{
    Network: greywall.NetworkConfig{
        AllowedDomains: []string{
            "registry.npmjs.org",
            "*.github.com",
            "api.openai.com",
        },
    },
}

```

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

### Extend Local Config File with Command Restrictions

Source: https://docs.greywall.io/greywall/templates

Extend another configuration file using a relative path. This example inherits settings from './shared/base-config.json' and adds a restriction to deny 'git push' commands.

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

```

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

### Generate Configuration via Learning Mode

Source: https://docs.greywall.io/greywall/faq

Automatically trace filesystem access to generate a configuration template.

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

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

### Build Greyproxy from Source

Source: https://docs.greywall.io/greyproxy/quickstart

Clone the repository and build the greyproxy binary from source. This method is useful for development or if pre-built binaries are not available.

```bash
git clone https://github.com/greyhavenhq/greyproxy.git
cd greyproxy
go build ./cmd/greyproxy
```

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

### Show Template Content

Source: https://docs.greywall.io/greywall/cli-reference

Print the configuration content of a specific learned template.

```bash
greywall templates show opencode  
```

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

### Clone and Build Greywall

Source: https://docs.greywall.io/greywall/contributing

Clone the repository, navigate to the directory, and set up the project dependencies and build the binary.

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

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

### Expose Dev Server Port and Wrap Command

Source: https://docs.greywall.io/greywall/library

Demonstrates how to set up a Greywall manager to expose specific ports for a development server and wrap a command for execution. Ensure to call Cleanup when done.

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

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

```

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

### Build Greywall from Source

Source: https://docs.greywall.io/greywall

Clones the Greywall repository and builds it from source using make commands.

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

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

### Install Linux Dependencies

Source: https://docs.greywall.io/greywall/quickstart

Installs required dependencies for Greywall on various Linux distributions. Ensure you have the necessary package manager privileges.

```bash
# Ubuntu/Debian  
sudo apt install bubblewrap socat  
  
# Fedora  
sudo dnf install bubblewrap socat  
  
# Arch  
sudo pacman -S bubblewrap socat  

```

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

### Manage Templates

Source: https://docs.greywall.io/greywall/learning-mode

Commands for listing and displaying generated configuration templates.

```bash
greywall templates list  
```

```bash
greywall templates show opencode  
```

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

### Access Help

Source: https://docs.greywall.io/greyproxy/cli-reference

Commands to display help information for the CLI or specific subcommands.

```bash
greyproxy help
greyproxy help serve
```

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

### Execute Learning Mode

Source: https://docs.greywall.io/greywall/learning-mode

Initiates the command within a relaxed filesystem sandbox to trace and log all filesystem-related syscalls.

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

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

### Combining Agent and Toolchain Profiles

Source: https://docs.greywall.io/greywall

Demonstrates how to combine agent profiles with toolchain profiles for specific development environments.

```bash
# Agent + Python toolchain  
greywall --profile claude,python -- claude  
```

```bash
# Agent + multiple toolchains  
greywall --profile opencode,node,go -- opencode  
```

```bash
# List all available and saved profiles  
greywall profiles list  
```

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

### greyproxy service

Source: https://docs.greywall.io/greyproxy/cli-reference

Manages the installed greyproxy service.

```APIDOC
## greyproxy service

### Description
Manages the installed greyproxy service without uninstalling it.

### Parameters
#### Path Parameters
- **subcommand** (string) - Required - The action to perform: status, start, stop, or restart.
```

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

### Load and Extend Greywall Configuration

Source: https://docs.greywall.io/greywall/library

Shows how to load a Greywall configuration from a default path, handle potential errors, and extend it by adding new command restrictions. If no config is found, it defaults to a basic configuration.

```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 Greyproxy with Custom Configuration

Source: https://docs.greywall.io/greyproxy/troubleshooting

If default ports are in use, you can run greyproxy with a custom configuration file to specify different ports.

```bash
greyproxy serve -C ~/greyproxy-custom.yml  
```

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

### Import Claude Code Settings

Source: https://docs.greywall.io/greywall/cli-reference

Convert Claude Code settings into a greywall configuration.

```bash
greywall import --claude  
greywall import --claude --save  
greywall import --claude -f ~/.claude/settings.json --save  
```

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

### Uninstall Greyproxy

Source: https://docs.greywall.io/greyproxy/quickstart

Removes the greyproxy installation and any associated services.

```bash
greyproxy uninstall
```

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

### Cross-Platform Benchmark Comparison

Source: https://docs.greywall.io/greywall/benchmarking

Compares benchmark results between macOS and Linux by running Go microbenchmarks on each platform and then using 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  
```

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

### Manage Greyproxy Service

Source: https://docs.greywall.io/greyproxy/quickstart

Commands to manage the greyproxy systemd user service after installation.

```bash
greyproxy service status
```

```bash
greyproxy service start
```

```bash
greyproxy service stop
```

```bash
greyproxy service restart
```

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

### Run Linux Integration Tests

Source: https://docs.greywall.io/greywall/contributing

Execute integration and Linux-specific tests for the sandbox module using Go's testing framework.

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

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

### Combining Flags

Source: https://docs.greywall.io/greywall/cli-reference

Examples of combining global flags for specific monitoring and debugging needs.

```APIDOC
### `-m` and `-d` together

You can combine both flags to get violation monitoring **and** the full sandbox command:

```
greywall -m -d -- npm install
```

### `-p / --port`

Expose ports for sandboxed servers so external processes can connect:

```
# Single port
greywall -p 3000 -c "npm run dev"

# Multiple ports
greywall -p 3000 -p 8080 -c "make start"
```
```

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

### Template JSONC Structure

Source: https://docs.greywall.io/greywall/learning-mode

Example of the generated JSONC configuration file format used by Greywall.

```json
// 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.*"  
    ]  
  }  
}  
```

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

### Configure Filesystem Write Permissions

Source: https://docs.greywall.io/greywall/faq

Define allowed and denied write paths in the configuration file. Deny rules take precedence over allow rules.

```json
{
  "filesystem": {
    "allowWrite": ["."],
    "denyWrite": [".env", ".git/hooks"]
  }
}
```

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

### Integration Test Helpers in Go

Source: https://docs.greywall.io/greywall/testing

Provides helpers for writing sandbox tests, including skipping tests based on conditions, running commands under a sandbox, and asserting test results and file existence. Use `testConfig` variants to set up sandbox configurations.

```go
// Skip helpers  
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  
```

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

### List All Rules API

Source: https://docs.greywall.io/greyproxy/rules

Use this command to retrieve a list of all currently configured rules from the greyproxy API.

```bash
curl http://localhost:43080/api/rules
```

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

### Run Project Tests

Source: https://docs.greywall.io/greywall/testing

Commands to execute the full test suite, unit tests, or specific integration tests.

```bash
# Run all tests  
make test  
  
# Run unit tests  
go test ./...  
  
# Run integration tests  
go test -v -run 'TestIntegration|TestLinux|TestMacOS' ./internal/sandbox/...  
  
# Run smoke tests (end-to-end)  
.https://github.com/GreyhavenHQ/greywall/blob/main/scripts/smoke_test.sh
```

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

### Add bwrap to PATH

Source: https://docs.greywall.io/greywall/faq

If 'bwrap' is installed but not on your PATH, add its directory to your PATH environment variable. This should be added to your shell profile for persistence.

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

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

### Profile CPU Usage

Source: https://docs.greywall.io/greywall/benchmarking

Generate a CPU profile for benchmarked code. Run the benchmark with the `-cpuprofile` flag and then use `go tool pprof` to analyze the profile, optionally with an HTTP server.

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

```

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

### Verify ~/.local/bin is in PATH

Source: https://docs.greywall.io/greyproxy/troubleshooting

After installing greyproxy, ensure that '~/.local/bin' is included in your system's PATH environment variable. If not, add it temporarily or permanently to your shell profile.

```bash
echo $PATH | grep -o '\.local/bin'  
# If empty, add it:  
export PATH="$HOME/.local/bin:$PATH"  
```

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

### Configure Blocking of Dangerous Commands

Source: https://docs.greywall.io/greywall/library

Example of initializing a Greywall configuration to block specific dangerous commands. This prevents the execution of potentially harmful shell commands.

```go
cfg := &greywall.Config{
    Command: greywall.CommandConfig{
        Deny: []string{
            "rm -rf /",
            "git push",
            "npm publish",
        },
    },
}

```

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

### List Pending Requests using curl

Source: https://docs.greywall.io/greyproxy/api

Example using curl to list all pending requests currently held by the proxy. This is useful for monitoring and managing traffic.

```bash
curl http://localhost:43080/api/pending
```

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

### Configure `greywall` for Restrictive PyPI Access

Source: https://docs.greywall.io/greywall/recipes/pip-poetry

This JSON configuration restricts filesystem writes to the current directory and /tmp. Use this as a starting point for `greywall` settings.

```json
{
  "filesystem": {
    "allowWrite": [".", "/tmp"]
  }
}

```

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

### Greyproxy CLI Synopsis

Source: https://docs.greywall.io/greyproxy/cli-reference

General usage pattern for the Greyproxy command-line tool.

```bash
greyproxy <subcommand> [flags]
```

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

### Add an Allow Rule using curl

Source: https://docs.greywall.io/greyproxy/api

Example using curl to add a new 'allow' rule to the proxy. This demonstrates how to send a JSON payload with a POST request.

```bash
curl -X POST http://localhost:43080/api/rules \
  -H "Content-Type: application/json" \
  -d '{"destination": "registry.npmjs.org", "port": 443, "action": "allow"}'
```

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

### Run Greywall in Monitor Mode

Source: https://docs.greywall.io/greyproxy/using-with-greywall

Execute a command with Greywall in monitor mode to observe network traffic and build an allow list. This is useful for initial project setup.

```bash
greywall -m -- npm install

```

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

### List Templates

Source: https://docs.greywall.io/greywall/cli-reference

Commands to list built-in or learned templates.

```bash
greywall --list-templates  
```

```bash
greywall templates list  
```

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

### Get Default Greywall Configuration

Source: https://docs.greywall.io/greywall/library

Obtain a default configuration object using `DefaultConfig()`. This configuration typically blocks all network access and enables deny-by-default filesystem reads.

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

```

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

### Profile Memory Usage

Source: https://docs.greywall.io/greywall/benchmarking

Generate a memory profile for benchmarked code. Run the benchmark with the `-memprofile` flag and then use `go tool pprof` to analyze the profile, optionally with an HTTP server.

```bash
# Memory profile  
go test -run=^$ -bench=BenchmarkWarmSandbox -memprofile=mem.out ./internal/sandbox/...  
go tool pprof -http=:8080 mem.out  

```

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

### Company-Specific AI Agent Configuration

Source: https://docs.greywall.io/greywall/templates

An example of a company-specific AI agent configuration that extends the 'code' template. It denies reading secret directories and publishing commands while protecting sensitive files.

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

```

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

### Specify Claude Code Settings File Path for Import

Source: https://docs.greywall.io/greywall/import-claude

If Claude Code is installed in a non-standard location, use the `-f` flag to explicitly point Greywall to its settings file during the import process.

```bash
greywall import --claude -f /path/to/claude/settings.json  
```

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

### Load Greywall Configuration from File

Source: https://docs.greywall.io/greywall/library

Load configuration from a JSON file using `LoadConfig()`. This function supports JSONC (comments) and returns an error if loading fails. If the file does not exist, it defaults 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  
}

```

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

### Configure Local Binding and Port Exposure

Source: https://docs.greywall.io/greywall/troubleshooting

When running a server within the sandbox that needs to accept external connections, set 'network.allowLocalBinding' to true and use the '-p <port>' flag to expose the necessary inbound ports.

```json
{
  "network": { "allowLocalBinding": true }
}

```

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

### Run All Go Microbenchmarks

Source: https://docs.greywall.io/greywall/benchmarking

Executes all Go microbenchmarks within the internal/sandbox directory to measure component-level overhead. Includes memory usage flags.

```go
# 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  
```

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

### Build Greywall for Linux Locally

Source: https://docs.greywall.io/greywall/contributing

Compile the Greywall binary specifically for the Linux platform.

```bash
make build-linux
```

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

### List Profiles

Source: https://docs.greywall.io/greywall/cli-reference

List all available built-in and saved custom profiles.

```bash
greywall profiles list  
```

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

### Run Greyproxy in Foreground with Debug Logging

Source: https://docs.greywall.io/greyproxy/troubleshooting

To enable verbose logging and see debug output, run the 'greyproxy serve' command with your configuration file. This will log directly to standard output.

```bash
greyproxy serve -C greyproxy.yml  # runs in foreground, logs to stdout  
```

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

### Benchmark Before Changes

Source: https://docs.greywall.io/greywall/benchmarking

Run benchmarks before making code changes and save the output to a file. Use `-count=10` for more stable results.

```bash
# Before  
go test -run=^$ -bench=. -count=10 ./internal/sandbox/... > before.txt  

```

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

### macOS Sandbox Flowchart

Source: https://docs.greywall.io/greywall/architecture

Illustrates the macOS sandbox execution flow using sandbox-exec and environment variables for network proxying.

```mermaid
flowchart LR
    subgraph macOS Sandbox
        CMD["User Command"]
        SE["sandbox-exec -p profile"]
        ENV["Environment Variables<br/>HTTP_PROXY, HTTPS_PROXY<br/>ALL_PROXY"]
    end
    CMD --> SE
    SE --> ENV

```

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

### Greywall Workflow: Import, Review, Run, Monitor

Source: https://docs.greywall.io/greywall/import-claude

This sequence outlines the typical workflow after importing Claude Code permissions: import, review the generated config, run Claude Code sandboxed, and use monitor mode.

```bash
# 1. Import existing Claude Code permissions  
greywall import --claude --save  

# 2. Review the generated config  
cat ~/.config/greywall/greywall.json  

# 3. Run Claude Code sandboxed — greywall auto-loads the config  
greywall -- claude  

# 4. Use monitor mode to catch anything that's missing  
greywall -m -- claude  
```
Tokens:
Raw