{"id":35824664,"url":"https://github.com/coder/boundary","last_synced_at":"2026-01-16T09:53:01.168Z","repository":{"id":316435336,"uuid":"1048674881","full_name":"coder/boundary","owner":"coder","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-12T18:53:11.000Z","size":24740,"stargazers_count":13,"open_issues_count":22,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T22:58:25.284Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"audit/log_auditor.go","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T20:52:20.000Z","updated_at":"2026-01-12T18:51:36.000Z","dependencies_parsed_at":"2025-09-24T16:32:27.966Z","dependency_job_id":"1fc272e5-93cf-4191-b11e-4197f3199e8e","html_url":"https://github.com/coder/boundary","commit_stats":null,"previous_names":["coder/boundary"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/coder/boundary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fboundary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fboundary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fboundary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fboundary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coder","download_url":"https://codeload.github.com/coder/boundary/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fboundary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-07T19:14:03.591Z","updated_at":"2026-01-16T09:53:01.155Z","avatar_url":"https://github.com/coder.png","language":"Go","readme":"# boundary\n\nNetwork isolation tool for monitoring and restricting HTTP/HTTPS requests from processes.\n\nboundary creates an isolated network environment for target processes, intercepting HTTP/HTTPS traffic through a transparent proxy that enforces user-defined allow rules.\n\n## Features\n\n - Process-level network isolation (Linux namespaces)\n- HTTP/HTTPS interception with transparent proxy and TLS certificate injection\n- Wildcard pattern matching for URL patterns\n- Request logging and monitoring\n - Linux support\n- Default deny-all security model\n\n## Installation\n\n### Quick Install (Recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/coder/boundary/main/install.sh | bash\n```\n\n\u003e For installation options, manual installation, and release details, see [RELEASES.md](RELEASES.md).\n\n### From Source\n\nBuild `boundary` from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/coder/boundary.git\ncd boundary\n\n# Build the binary\nmake build\n\n# Install binary and wrapper script (optional)\nsudo cp boundary /usr/local/bin/\nsudo cp scripts/boundary-wrapper.sh /usr/local/bin/boundary-run\nsudo chmod +x /usr/local/bin/boundary-run\n```\n\n**Requirements:**\n- Go 1.24 or later\n- Linux\n\n## Usage\n\n### Quick Start with Shortcut\n\nThe 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:\n\n```bash\n# After installation, use the shortcut:\nboundary-run --allow \"domain=github.com\" -- curl https://github.com\nboundary-run -- bash\n```\n\n\u003e **Note:** If you installed `boundary` manually, you can install the wrapper script separately:\n\u003e ```bash\n\u003e sudo cp scripts/boundary-wrapper.sh /usr/local/bin/boundary-run\n\u003e sudo chmod +x /usr/local/bin/boundary-run\n\u003e ```\n\n### Direct Usage\n\nIf you prefer to run `boundary` directly, you'll need to handle privilege escalation:\n\n```bash\n# Note: sys_admin is only needed in restricted environments (e.g., Docker with seccomp).\n# If boundary works without it on your system, you can remove +sys_admin from both flags.\nsudo -E env PATH=$PATH setpriv \\\n  --reuid=$(id -u) \\\n  --regid=$(id -g) \\\n  --clear-groups \\\n  --inh-caps=+net_admin,+sys_admin \\\n  --ambient-caps=+net_admin,+sys_admin \\\n  boundary --allow \"domain=github.com\" -- curl https://github.com\n```\n\n### Examples\n\n```bash\n# Allow only requests to github.com\nboundary-run --allow \"domain=github.com\" -- curl https://github.com\n\n# Allow full access to GitHub issues API, but only GET/HEAD elsewhere on GitHub\nboundary-run \\\n  --allow \"domain=github.com path=/api/issues/*\" \\\n  --allow \"method=GET,HEAD domain=github.com\" \\\n  -- npm install\n\n# Default deny-all: everything is blocked unless explicitly allowed\nboundary-run -- curl https://example.com\n```\n\n## Allow Rules\n\n### Format\n```text\n--allow \"key=value [key=value ...]\"\n```\n\n**Keys:**\n- `method` - HTTP method(s), comma-separated (GET, POST, etc.)\n- `domain` - Domain/hostname pattern\n- `path` - URL path pattern(s), comma-separated\n\n### Examples\n```bash\nboundary-run --allow \"domain=github.com\" -- git pull\nboundary-run --allow \"domain=*.github.com\" -- npm install           # GitHub subdomains\nboundary-run --allow \"domain=github.com\" --allow \"domain=*.github.com\" -- git pull  # Both base domain and subdomains\nboundary-run --allow \"method=GET,HEAD domain=api.github.com\" -- curl https://api.github.com\nboundary-run --allow \"method=POST domain=api.example.com path=/users,/posts\" -- ./app  # Multiple paths\nboundary-run --allow \"path=/api/v1/*,/api/v2/*\" -- curl https://api.example.com/api/v1/users\n```\n\nWildcards: `*` matches any characters. All traffic is denied unless explicitly allowed.\n\n## Logging\n\n```bash\nboundary-run --log-level warn --allow \"domain=github.com\" -- git pull  # Default: only logs denied requests\nboundary-run --log-level info --allow \"method=*\" -- npm install     # Show all requests\nboundary-run --log-level debug --allow \"domain=github.com\" -- git pull  # Debug info\n```\n\n**Log Levels:** `error`, `warn` (default), `info`, `debug`\n\n## Audit Logs\n\nBoundary tracks all HTTP/HTTPS requests that pass through the transparent proxy, recording\nwhether each request was allowed or denied. This provides visibility into network access\npatterns for monitoring and compliance. By default, all requests are logged to stderr using\nstructured logging.\n\n### Coder Integration\n\nWhen running inside a Coder workspace, boundary can forward audit logs to the workspace\nagent, which then sends them to coderd for centralized logging. The intention is for\nthese logs to work out of the box when an AI agent runs in a workspace using a module\nthat has boundary enabled (e.g. the [Claude Code](https://registry.coder.com/modules/coder/claude-code)\nmodule), and when `boundary-run` is used directly.\n\n**How it works:**\n\n1. The workspace agent runs a Unix socket server at a configurable path (see:\n   `--log-proxy-socket-path`)\n2. Boundary connects to this socket and streams audit event batches using a [protobuf-based\n   protocol](https://github.com/coder/coder/blob/0c5809726d61c628ecbd359ae47bb85e83700681/agent/boundarylogproxy/codec/codec.go)\n   - If the socket doesn't exist when boundary starts, a warning is logged to stderr and\n   no audit logs are forwarded. This will occur on versions of coder that do not yet support\n   forwarding boundary audit logs\n3. The workspace agent forwards these logs to coderd\n4. coderd emits the logs as structured log entries for ingestion by log aggregation systems\n\n## Platform Support\n\n| Platform | Implementation                 | Privileges                |\n|----------|--------------------------------|---------------------------|\n| Linux    | Network namespaces + iptables  | CAP_NET_ADMIN (or root)   |\n| macOS    | Not supported                  | -                         |\n| Windows  | Not supported                  | -                         |\n\n## Security and Privileges\n\n**All processes are expected to run as non-root users** for security best practices:\n\n- **boundary-parent**: The main boundary process that sets up network isolation\n- **boundary-child**: The child process created within the network namespace\n- **target/agent process**: The command you're running (e.g., `curl`, `npm`, `bash`)\n\nThe `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.\n\nIf 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.\n\n## Command-Line Options\n\n```text\nboundary-run [flags] -- command [args...]\n\n --config \u003cPATH\u003e                  Path to YAML config file (default: ~/.config/coder_boundary/config.yaml)\n --allow \u003cSPEC\u003e                   Allow rule (repeatable). Merged with allowlist from config file\n --log-level \u003cLEVEL\u003e              Set log level (error, warn, info, debug). Default: warn\n --log-dir \u003cDIR\u003e                  Directory to write logs to (default: stderr)\n --proxy-port \u003cPORT\u003e              HTTP proxy port (default: 8080)\n --pprof                          Enable pprof profiling server\n --pprof-port \u003cPORT\u003e              pprof server port (default: 6060)\n --disable-audit-logs             Disable sending audit logs to the workspace agent\n --log-proxy-socket-path \u003cPATH\u003e   Path to the audit log socket\n -h, --help                       Print help\n```\n\nEnvironment 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`\n\n## Development\n\n```bash\nmake build          # Build for current platform\nmake build-all      # Build for all platforms\nmake test           # Run tests\nmake test-coverage  # Run tests with coverage\nmake clean          # Clean build artifacts\nmake fmt            # Format code\nmake lint           # Lint code\n```\n\n## Architecture\n\nFor detailed information about how `boundary` works internally, see [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## License\n\nMIT License - see LICENSE file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder%2Fboundary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoder%2Fboundary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder%2Fboundary/lists"}