Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
812c24b
feat(bwopencode2): add --serve to run the web UI server in the sandbox
stuwilkins Nov 8, 2026
afa0568
feat(bwopencode2): print a one-time pairing link for --serve
stuwilkins Nov 8, 2026
1f47dff
feat(bwrap): open bwrap's descriptors in a relay before exec
tacaswell Oct 30, 2026
46c1adf
feat(bwrap): run every sandbox in a private network namespace
tacaswell Oct 30, 2026
6cacc54
docs(bwrap): describe the private network namespace
tacaswell Oct 30, 2026
5568370
feat(bwrap): fall back to the host network without pasta
tacaswell Oct 30, 2026
3471dcb
refactor(bwrap): rename --local-net to --share-net
tacaswell Oct 30, 2026
8d9222d
feat(bwrap): stop instead of sharing the host network
tacaswell Oct 30, 2026
75fd847
feat(bwrap): add slirp4netns as a second network backend
tacaswell Oct 30, 2026
8f828bc
docs(bwrap): describe the backend choice and slirp4netns
tacaswell Oct 30, 2026
d4acce7
feat(bwopencode2): publish the --serve port in the private network
tacaswell Nov 10, 2026
ee7dc8c
fix(bwrap): keep network launch files in a checked runtime directory
tacaswell Nov 10, 2026
5e51225
fix(bwrap): signal only the launcher's own processes on slirp failure
tacaswell Nov 10, 2026
7d24a2f
fix(bwrap): claim publish addresses under a lock
tacaswell Nov 10, 2026
c612835
docs(bwrap): describe the backend choice in the library header
tacaswell Nov 10, 2026
580d8aa
refactor(bwrap): remove --net-log FILE
tacaswell Nov 10, 2026
b071672
feat(bwrap): always log network sessions and pasta flows to the syste…
tacaswell Nov 10, 2026
4aa3c8c
test(bwrap): add fake network backends to run the launchers
tacaswell Nov 10, 2026
4784f93
fix(bwopencode2): always serve on the user's first publish address
tacaswell Nov 10, 2026
7943d1d
fix(bwrap): forward --host-port to the sandbox's own loopback
tacaswell Nov 10, 2026
3361154
feat(bwrap): condense the network log and name destinations
tacaswell Nov 10, 2026
67717c1
test(bwrap): test the network log condenser and DNS relay
tacaswell Nov 10, 2026
a73e6f3
fix(bwrap): log DNS answers before relaying them, split out CNAMEs
tacaswell Nov 10, 2026
efb5fad
refactor(bwrap): call the destination's DNS name domain= in the netwo…
tacaswell Nov 10, 2026
ff20544
build(lint): run actionlint from pixi instead of building it from source
tacaswell Nov 10, 2026
733cfc1
feat(bwrap): mount the prek cache read-write
tacaswell Nov 10, 2026
af19ed6
fix(bwrap): bound network helpers and test regressions
tacaswell Nov 10, 2026
ee59027
fix(bwrap): log pasta flows over stderr, not --log-file, for SELinux
tacaswell Nov 12, 2026
f5126ee
refactor(bwrap): let the condenser read the netlog FIFO itself
tacaswell Nov 12, 2026
d73a2ec
fix(bwrap): run slirp4netns sandboxes under an identity map
tacaswell Nov 13, 2026
2829124
feat(bwrap): log DNS lookups under slirp4netns too
tacaswell Nov 13, 2026
6918ce7
fix(bwrap): drop the untested pasta and bwrap 0.4.0 check
tacaswell Nov 13, 2026
41147bb
docs(bwrap): explain how the network log is written and read
tacaswell Nov 13, 2026
c31325c
fix(bwcodex): drop --perms so it works with bwrap 0.4.0
tacaswell Nov 13, 2026
e8738f0
Change shell command from sh to bash it test
tacaswell Nov 13, 2026
2d459f1
feat(bwrap): name the user on every network log record
stuwilkins Nov 15, 2026
d1c9bad
fix(bwrap): address the Copilot review of the network log
stuwilkins Nov 16, 2026
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
1 change: 1 addition & 0 deletions .codespell.ignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
passt
3 changes: 3 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,9 @@ jobs:
2>&1 | tee /tmp/prek-output.txt
fi

- name: Run unit tests
run: pixi run -e dev test

- name: Write job summary
if: always()
env:
Expand Down
11 changes: 9 additions & 2 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -95,10 +95,17 @@ repos:
entry: pixi run --frozen -e dev yamllint
types: [yaml]

- repo: https://github.com/rhysd/actionlint
rev: v1.7.12
# From pixi (conda-forge) rather than the upstream hook, which is
# `language: golang` and builds actionlint from source: a Go toolchain and
# its modules downloaded in every fresh environment.
- repo: local
hooks:
- id: actionlint
name: actionlint (pixi dev)
language: system
entry: pixi run --frozen -e dev actionlint
types: [yaml]
files: '^\.github/workflows/'

- repo: local
hooks:
Expand Down
6 changes: 5 additions & 1 deletion AI_DISCLOSURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,16 @@
tools-used:
- OpenCode
models-used:
- claude-fable-5-2
- claude-opus-4-8
- claude-opus-5-5
- claude-sonnet-4-6
- claude-sonnet-5
- claude-sonnet-5-5
- gpt-5.6-sol
- gpt-6-astra
- gpt-6-sol
- gpt-6.1-sol
providers:
- Anthropic
- OpenAI
Expand All @@ -19,7 +23,7 @@ scope:
Shell wrapper scripts (bin/, lib/), the `azoidcapp` Python helper,
documentation (docs/), and CI/lint configuration — all with human
review and validation.
last-updated: 2026-10-24
last-updated: 2026-11-16
---

# AI Disclosure
Expand Down
15 changes: 14 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,14 @@ Add those three exports to your `~/.bashrc` or `~/.zshrc` for persistence.
- `bash` >= 4.x (the `bw*` wrappers use `[[ ]]` and arrays)
- `bubblewrap` (`bwrap`) >= 0.4.0 for the `bw*` wrappers
- binary masking is verified on RHEL 8.10 (`bubblewrap-0.4.0-3.el8_10`) and EL9 (0.6.3)
- GNU `timeout` (coreutils) to bound the `pasta` network-backend probe
- `pasta` (package `passt`, RHEL 9+) or `slirp4netns` (RHEL 8 AppStream),
with `/dev/net/tun` and unprivileged user namespaces, for the private network
namespace of the `bw*` wrappers; without either they stop unless run with
`--share-net`
- `systemd-cat` (with a running journal) or `logger`, for the `bw*` wrappers'
always-on network log (tag `bwrap-net`); without either they warn and run
without it
- `gpg(1)` for `gpg-passwd.sh`
- `openssl(1)` for `pemdecompose`
- `python3 >= 3.9` (stdlib only, no pip dependencies) for `azoidcapp`
Expand All @@ -96,13 +104,18 @@ Common wrapper options:
| Option | Effect |
| --- | --- |
| `--help`, `-h` | Show wrapper help, then the underlying tool's help when the tool is installed |
| `--dry-run` | Print the `bwrap` command without executing it |
| `--dry-run` | Print the command (network backend, descriptor relay, `bwrap`) without executing it |
| `--exec CMD [ARGS...]` | Run `CMD` inside the sandbox instead of the tool. `CMD` is split on whitespace; following arguments are passed unchanged, e.g. `--exec bash -c 'env \| sort'` |
| `--init-auth` | Persist auth credentials to the host (first-time setup) |
| `--new-session` | Force `bwrap --new-session` (stricter isolation; breaks SIGWINCH) |
| `--ro-path PATH`, `--rw-path PATH` | Mount an existing path read-only / read-write (may be repeated and nested) |
| `--github-tokens` | Forward `GH_TOKEN_*` variables so `gh` can authenticate inside the sandbox (off by default) |
| `--no-sandbox-context` | Do not tell the agent about the sandbox (by default a short description of the mounts is added to its instructions) |
| `--publish PORT[:SANDBOXPORT]` | Make a server in the sandbox reachable on the host at a per-user, per-session `127.x.y.z` address (printed at launch) |
| `--publish-addr ADDR` | Use `ADDR` (in `127.0.0.0/8`, e.g. `127.0.0.1` for OAuth) for `--publish` |
| `--host-port PORT[:SANDBOXPORT]` | Make the host's `127.0.0.1:PORT` reachable in the sandbox at `127.0.0.1:SANDBOXPORT` (pasta only) |
| `--share-net` | Share the host network instead of a private namespace (the behaviour before private namespaces) |
| `--net-backend pasta\|slirp4netns` | Use only this network backend |

`bwclaude` also supports `--debug`. `bwopencode2` has no `--init-auth` (sign-in
persists in its data directory), always runs OpenCode 2 with `--standalone`
Expand Down
82 changes: 67 additions & 15 deletions bin/bwclaude
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,29 @@
# so `--rw-path DIR --ro-path DIR/sub` protects DIR/sub.
# --no-sandbox-context
# Do not generate the sandbox context file (see below).
# --publish PORT[:SANDBOXPORT]
# Make a server in the sandbox reachable on the host at a
# per-user, per-session loopback address (127.H1.H2.S:PORT).
# May be repeated.
# --publish-addr ADDR
# Use ADDR (in 127.0.0.0/8) for --publish instead.
# --host-port PORT[:SANDBOXPORT]
# Make the host's 127.0.0.1:PORT reachable in the sandbox at
# 127.0.0.1:SANDBOXPORT (pasta only; that sandbox port is
# then taken). May be repeated.
# --share-net Share the host network instead (the behaviour before
# private namespaces); not with the options above.
# --net-backend pasta|slirp4netns
# Use only this backend for the private namespace.
#
# Network: the sandbox has its own network namespace from pasta (package
# passt), or else slirp4netns (--host-port needs pasta).
# Outbound connections work; services on the host's loopback are unreachable
# and the sandbox's listeners are invisible to the host, except for the ports
# opened with --publish and --host-port. Without a usable private namespace
# the launch stops (exit 3) unless --share-net is given. Every session (with
# pasta every connection too) is recorded in the host's system log, tag
# bwrap-net; there is no option to turn this off.
#
# Sandbox context: a short markdown file describing this sandbox (what is
# mounted read-only or read-write, what is lost at exit, which tools are
Expand Down Expand Up @@ -164,6 +187,42 @@ parse_wrapper_args() {
SANDBOX_CONTEXT_ENABLED=0
shift
;;
--publish)
if [[ $# -lt 2 ]]; then
echo "Error: --publish requires PORT[:SANDBOXPORT]." >&2
exit 1
fi
net_add_publish "$2"
shift 2
;;
--publish-addr)
if [[ $# -lt 2 ]]; then
echo "Error: --publish-addr requires an address in 127.0.0.0/8." >&2
exit 1
fi
net_set_publish_addr "$2"
shift 2
;;
--host-port)
if [[ $# -lt 2 ]]; then
echo "Error: --host-port requires PORT[:SANDBOXPORT]." >&2
exit 1
fi
net_add_host_port "$2"
shift 2
;;
--share-net)
net_set_share
shift
;;
--net-backend)
if [[ $# -lt 2 ]]; then
echo "Error: --net-backend requires pasta or slirp4netns." >&2
exit 1
fi
net_set_backend "$2"
shift 2
;;
--ro-path)
if [[ $# -lt 2 ]]; then
echo "Error: --ro-path requires a path argument." >&2
Expand Down Expand Up @@ -263,6 +322,7 @@ Authentication:
bwclaude --init-auth

HELP_EOF
net_print_help
# Delegate to claude --help inside the sandbox so the user sees the full
# claude option set in the same invocation.
bwrap_show_tool_help claude
Expand Down Expand Up @@ -354,14 +414,8 @@ build_claude_home_mount() {
BWRAP_ARGS+=(--bind "${_settings_path}" "${_settings_path}")
fi
elif [[ -f "${_settings_path}" ]]; then
if [[ "${DRY_RUN}" -eq 1 ]]; then
# A real fd number could not be reproduced by copy-paste.
BWRAP_ARGS+=(--file "<settings-fd>" "${_settings_path}")
else
local _settings_fd
exec {_settings_fd}< "${_settings_path}"
BWRAP_ARGS+=(--file "${_settings_fd}" "${_settings_path}")
fi
bwrap_fd_from_file "${_settings_path}"
BWRAP_ARGS+=(--file "${_BWRAP_FD}" "${_settings_path}")
fi

# Persistent read-only config file (if it exists)
Expand All @@ -383,13 +437,8 @@ build_claude_home_mount() {
elif [[ -f "${CLAUDE_CREDENTIALS_FILE}" ]]; then
# Normal mode: copy credentials into tmpfs via --file so host auth is
# available but changes don't persist.
if [[ "${DRY_RUN}" -eq 1 ]]; then
BWRAP_ARGS+=(--file "<credentials-fd>" "${CLAUDE_CREDENTIALS_FILE}")
else
local _fd
exec {_fd}< "${CLAUDE_CREDENTIALS_FILE}"
BWRAP_ARGS+=(--file "${_fd}" "${CLAUDE_CREDENTIALS_FILE}")
fi
bwrap_fd_from_file "${CLAUDE_CREDENTIALS_FILE}"
BWRAP_ARGS+=(--file "${_BWRAP_FD}" "${CLAUDE_CREDENTIALS_FILE}")
fi

# State file (~/.claude.json, or $CLAUDE_CONFIG_DIR/.claude.json): bind RW
Expand Down Expand Up @@ -593,6 +642,7 @@ main() {
bwrap_resolve_tool claude

detect_kernel_capabilities
detect_net_capabilities
resolve_common_paths
resolve_claude_paths
detect_shell
Expand All @@ -608,6 +658,7 @@ main() {
build_proc_dev_tmp
build_sys_mounts
build_etc_mounts
build_net_isolation
build_managed_claude_paths
build_home_tmpfs
build_workdir_mount
Expand All @@ -618,6 +669,7 @@ main() {
build_pixi_mounts
build_ccache_mounts
build_npm_mounts
build_prek_mounts
build_user_bin_mount
build_nsls2_mount
build_claude_bin_mount
Expand Down
Loading