Skip to content

quickstart.md

Latest commit

 

History

History
174 lines (115 loc) · 3.5 KB

quickstart.md

File metadata and controls

174 lines (115 loc) · 3.5 KB

Quickstart

Installation

Homebrew (macOS)

brew tap use-tusk/tap
brew install use-tusk/tap/fence

To update:

brew upgrade use-tusk/tap/fence

Nix (macOS, Linux, Windows (WSL))

nix run nixpkgs#fence -- --help

This runs it directly from the repository, without installing fence. If you want to install it, follow the guidelines from NixOS or nix-darwin.

From Source

git clone https://github.com/Use-Tusk/fence
cd fence
go build -o fence ./cmd/fence
sudo mv fence /usr/local/bin/

Using Go Install

go install github.com/Use-Tusk/fence/cmd/fence@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 fence?

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

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

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

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

Verify Installation

fence --version

Your First Sandboxed Command

By default, fence blocks all network access:

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

You should see something like:

curl: (56) CONNECT tunnel failed, response 403

Allow Specific Domains

Create a starter config:

fence config init

By default, this writes {"extends":"code"} to $XDG_CONFIG_HOME/fence/fence.json on Linux (typically ~/.config/fence/fence.json) and ~/.config/fence/fence.json on macOS, so common coding workflows work out of the box.

If you want a starter file with empty arrays as editable hints, use:

fence config init --scaffold

You can also create a fully custom config manually:

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

Now try again:

fence curl https://example.com

This time it succeeds!

Debug Mode

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

fence -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:

fence -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:

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

Expose Ports for Servers

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

fence -p 3000 -c "npm run dev"

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

Next steps

  • Read Why Fence to understand when fence 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).