boundary

Network isolation tool for monitoring and restricting HTTP/HTTPS requests from processes.

boundary creates an isolated network environment for target processes, intercepting HTTP/HTTPS traffic through a transparent proxy that enforces user-defined allow rules.

Features

• Process-level network isolation (Linux namespaces)
• HTTP/HTTPS interception with transparent proxy and TLS certificate injection
• Wildcard pattern matching for URL patterns
• Request logging and monitoring
• Linux support
• Default deny-all security model

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/coder/boundary/main/install.sh | bash

For installation options, manual installation, and release details, see RELEASES.md.

From Source

Build boundary from source:

# Clone the repository
git clone https://github.com/coder/boundary.git
cd boundary

# Build the binary
make build

# Install binary
sudo cp boundary /usr/local/bin/

Requirements:

• Go 1.24 or later
• Linux

Usage

Quick Start

When using the default nsjail backend, boundary escalates privileges automatically (via sudo and setpriv) to acquire the necessary capabilities:

boundary --allow "domain=github.com" -- curl https://github.com
boundary -- bash

Privilege escalation runs only when jail type is nsjail (the default). With landjail, no escalation is performed.

Examples

# Allow only requests to github.com
boundary --allow "domain=github.com" -- curl https://github.com

# Allow full access to GitHub issues API, but only GET/HEAD elsewhere on GitHub
boundary \
  --allow "domain=github.com path=/api/issues/*" \
  --allow "method=GET,HEAD domain=github.com" \
  -- npm install

# Default deny-all: everything is blocked unless explicitly allowed
boundary -- curl https://example.com

Allow Rules

Format

--allow "key=value [key=value ...]"

Keys:

• method - HTTP method(s), comma-separated (GET, POST, etc.)
• domain - Domain/hostname pattern
• path - URL path pattern(s), comma-separated

Examples

boundary --allow "domain=github.com" -- git pull
boundary --allow "domain=*.github.com" -- npm install           # GitHub subdomains
boundary --allow "domain=github.com" --allow "domain=*.github.com" -- git pull  # Both base domain and subdomains
boundary --allow "method=GET,HEAD domain=api.github.com" -- curl https://api.github.com
boundary --allow "method=POST domain=api.example.com path=/users,/posts" -- ./app  # Multiple paths
boundary --allow "path=/api/v1/*,/api/v2/*" -- curl https://api.example.com/api/v1/users

Wildcards: * matches any characters. All traffic is denied unless explicitly allowed.

Logging

boundary --log-level warn --allow "domain=github.com" -- git pull  # Default: only logs denied requests
boundary --log-level info --allow "method=*" -- npm install     # Show all requests
boundary --log-level debug --allow "domain=github.com" -- git pull  # Debug info

Log Levels: error, warn (default), info, debug

Audit Logs

Boundary tracks all HTTP/HTTPS requests that pass through the transparent proxy, recording whether each request was allowed or denied. This provides visibility into network access patterns for monitoring and compliance. By default, all requests are logged to stderr using structured logging.

Coder Integration

When running inside a Coder workspace, boundary can forward audit logs to the workspace agent, which then sends them to coderd for centralized logging. The intention is for these logs to work out of the box when an AI agent runs in a workspace using a module that has boundary enabled (e.g. the Claude Code module), and when boundary is used directly.

How it works:

1. The workspace agent runs a Unix socket server at a configurable path (see: --log-proxy-socket-path)
2. Boundary connects to this socket and streams audit event batches using a protobuf-based protocol
   • If the socket doesn't exist when boundary starts, a warning is logged to stderr and no audit logs are forwarded. This will occur on versions of coder that do not yet support forwarding boundary audit logs
3. The workspace agent forwards these logs to coderd
4. coderd emits the logs as structured log entries for ingestion by log aggregation systems

Platform Support

Platform	Implementation	Privileges
Linux	Network namespaces + iptables	CAP_NET_ADMIN (or root)
macOS	Not supported	-
Windows	Not supported	-

Security and Privileges

All processes are expected to run as non-root users for security best practices:

• boundary-parent: The main boundary process that sets up network isolation
• boundary-child: The child process created within the network namespace
• target/agent process: The command you're running (e.g., curl, npm, bash)

When using the nsjail backend (default), boundary escalates privileges itself: it re-executes via sudo and setpriv so that it runs with the minimum required capabilities (CAP_NET_ADMIN and optionally CAP_SYS_ADMIN for restricted environments) while still executing as your regular user.

Command-Line Options

boundary [flags] -- command [args...]

 --config <PATH>                  Path to YAML config file (default: ~/.config/coder_boundary/config.yaml)
 --allow <SPEC>                   Allow rule (repeatable). Merged with allowlist from config file
 --log-level <LEVEL>              Set log level (error, warn, info, debug). Default: warn
 --log-dir <DIR>                  Directory to write logs to (default: stderr)
 --proxy-port <PORT>              HTTP proxy port (default: 8080)
 --pprof                          Enable pprof profiling server
 --pprof-port <PORT>              pprof server port (default: 6060)
 --disable-audit-logs             Disable sending audit logs to the workspace agent
 --log-proxy-socket-path <PATH>   Path to the audit log socket
 -h, --help                       Print help

Environment variables: BOUNDARY_CONFIG, BOUNDARY_ALLOW, BOUNDARY_LOG_LEVEL, BOUNDARY_LOG_DIR, PROXY_PORT, BOUNDARY_PPROF, BOUNDARY_PPROF_PORT, DISABLE_AUDIT_LOGS, CODER_AGENT_BOUNDARY_LOG_PROXY_SOCKET_PATH

Development

make build          # Build for current platform
make build-all      # Build for all platforms
make test           # Run tests
make test-coverage  # Run tests with coverage
make clean          # Clean build artifacts
make fmt            # Format code
make lint           # Lint code

Architecture

For detailed information about how boundary works internally, see ARCHITECTURE.md.

License

MIT License - see LICENSE file for details.