Archived

This repository has been archived on 2026-03-13. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

Mathieu Virbel da3a2ac3a4 rename Fence to Greywall as GreyHaven sandboxing component

Rebrand the project from Fence to Greywall, the sandboxing layer of the
GreyHaven platform. This updates:

- Go module path to gitea.app.monadical.io/monadical/greywall
- Binary name, CLI help text, and all usage examples
- Config paths (~/.config/greywall/greywall.json), env vars (GREYWALL_*)
- Log prefixes ([greywall:*]), temp file prefixes (greywall-*)
- All documentation, scripts, CI workflows, and example files
- README rewritten with GreyHaven branding and Fence attribution

Directory/file renames: cmd/fence → cmd/greywall, pkg/fence → pkg/greywall,
docs/why-fence.md → docs/why-greywall.md, example JSON files, and banner.

2026-02-10 16:00:24 -06:00

2.9 KiB

Raw Permalink Blame History

Quickstart

Installation

From Source (recommended for now)

git clone https://gitea.app.monadical.io/monadical/greywall
cd greywall
go build -o greywall ./cmd/greywall
sudo mv greywall /usr/local/bin/

Using Go Install

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

Linux Dependencies

On Linux, you also need:

# Ubuntu/Debian
sudo apt install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

# Arch
sudo pacman -S bubblewrap socat

Do I need sudo to run greywall?

No, for most Linux systems. Greywall works without root privileges because:

Package-manager-installed bubblewrap is typically already setuid
Greywall detects available capabilities and adapts automatically

If some features aren't available (like network namespaces in Docker/CI), greywall falls back gracefully - you'll still get filesystem isolation, command blocking, and proxy-based network filtering.

Run greywall --linux-features to see what's available in your environment.

Verify Installation

greywall --version

Your First Sandboxed Command

By default, greywall blocks all network access:

# This will fail - network is blocked
greywall curl https://example.com

You should see something like:

curl: (56) CONNECT tunnel failed, response 403

Allow Specific Domains

Create a config file at ~/.config/greywall/greywall.json (or ~/Library/Application Support/greywall/greywall.json on macOS):

{
  "network": {
    "allowedDomains": ["example.com"]
  }
}

Now try again:

greywall curl https://example.com

This time it succeeds!

Debug Mode

Use -d to see what's happening under the hood:

greywall -d curl https://example.com

This shows:

The sandbox command being run
Proxy activity (allowed/blocked requests)
Filter rule matches

Monitor Mode

Use -m to see only violations and blocked requests:

greywall -m npm install

This is useful for:

Auditing what a command tries to access
Debugging why something isn't working
Understanding a package's network behavior

Running Shell Commands

Use -c to run compound commands:

greywall -c "echo hello && ls -la"

Expose Ports for Servers

If you're running a server that needs to accept connections:

greywall -p 3000 -c "npm run dev"

This allows external connections to port 3000 while keeping outbound network restricted.

Next steps

Read Why Greywall to understand when greywall is a good fit (and when it isn't).
Learn the mental model in Concepts.
Use Troubleshooting if something is blocked unexpectedly.
Start from copy/paste configs in docs/templates/.
Follow workflow-specific guides in Recipes (npm/pip/git/CI).

2.9 KiB Raw Permalink Blame History