Skip to content

docs: deprecate boundary-run #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
evgeniy-scherbina merged 1 commit into from
Jan 28, 2026
+21 −46
Merged

docs: deprecate boundary-run #160

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 21 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,8 @@ cd boundary
# Build the binary
make build

# Install binary and wrapper script (optional)
# Install binary
sudo cp boundary /usr/local/bin/
sudo cp scripts/boundary-wrapper.sh /usr/local/bin/boundary-run
sudo chmod +x /usr/local/bin/boundary-run
```

**Requirements:**
Expand All @@ -47,52 +45,31 @@ sudo chmod +x /usr/local/bin/boundary-run

## Usage

### Quick Start with Shortcut
### Quick Start

The recommended way to run `boundary` is using the `boundary-run` shortcut, which handles privilege escalation automatically. The `boundary-run` wrapper is installed automatically when you use the installation script:
When using the default nsjail backend, boundary escalates privileges automatically (via `sudo` and `setpriv`) to acquire the necessary capabilities:

```bash
# After installation, use the shortcut:
boundary-run --allow "domain=github.com" -- curl https://github.com
boundary-run -- bash
boundary --allow "domain=github.com" -- curl https://github.com
boundary -- bash
```

> **Note:** If you installed `boundary` manually, you can install the wrapper script separately:
> ```bash
> sudo cp scripts/boundary-wrapper.sh /usr/local/bin/boundary-run
> sudo chmod +x /usr/local/bin/boundary-run
> ```

### Direct Usage

If you prefer to run `boundary` directly, you'll need to handle privilege escalation:

```bash
# Note: sys_admin is only needed in restricted environments (e.g., Docker with seccomp).
# If boundary works without it on your system, you can remove +sys_admin from both flags.
sudo -E env PATH=$PATH setpriv \
--reuid=$(id -u) \
--regid=$(id -g) \
--clear-groups \
--inh-caps=+net_admin,+sys_admin \
--ambient-caps=+net_admin,+sys_admin \
boundary --allow "domain=github.com" -- curl https://github.com
```
Privilege escalation runs only when jail type is `nsjail` (the default). With `landjail`, no escalation is performed.

### Examples

```bash
# Allow only requests to github.com
boundary-run --allow "domain=github.com" -- curl https://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-run \
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-run -- curl https://example.com
boundary -- curl https://example.com
```

## Allow Rules
Expand All @@ -109,22 +86,22 @@ boundary-run -- curl https://example.com

### Examples
```bash
boundary-run --allow "domain=github.com" -- git pull
boundary-run --allow "domain=*.github.com" -- npm install # GitHub subdomains
boundary-run --allow "domain=github.com" --allow "domain=*.github.com" -- git pull # Both base domain and subdomains
boundary-run --allow "method=GET,HEAD domain=api.github.com" -- curl https://api.github.com
boundary-run --allow "method=POST domain=api.example.com path=/users,/posts" -- ./app # Multiple paths
boundary-run --allow "path=/api/v1/*,/api/v2/*" -- curl https://api.example.com/api/v1/users
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

```bash
boundary-run --log-level warn --allow "domain=github.com" -- git pull # Default: only logs denied requests
boundary-run --log-level info --allow "method=*" -- npm install # Show all requests
boundary-run --log-level debug --allow "domain=github.com" -- git pull # Debug info
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`
Expand All @@ -142,7 +119,7 @@ When running inside a Coder workspace, boundary can forward audit logs to the wo
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](https://registry.coder.com/modules/coder/claude-code)
module), and when `boundary-run` is used directly.
module), and when `boundary` is used directly.

**How it works:**

Expand Down Expand Up @@ -172,14 +149,12 @@ module), and when `boundary-run` is used directly.
- **boundary-child**: The child process created within the network namespace
- **target/agent process**: The command you're running (e.g., `curl`, `npm`, `bash`)

The `boundary-run` wrapper script handles privilege escalation automatically using `setpriv` to drop privileges before launching boundary. This ensures all processes run with the minimum required capabilities (`CAP_NET_ADMIN` and optionally `CAP_SYS_ADMIN` for restricted environments) while executing as your regular user account.

If you run `boundary` directly with `sudo` (without `setpriv`), all processes will run as root, which is **not recommended** for security reasons. Always use `boundary-run` or the equivalent `setpriv` command shown in the [Direct Usage](#direct-usage) section.
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

```text
boundary-run [flags] -- command [args...]
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
Expand Down
Loading