treebox 0.1.0__py3-none-any.whl

treebox/__init__.py

@@ -0,0 +1,8 @@
+"""treebox: isolated, ready-to-run git worktrees for AI coding agents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("treebox")
+except PackageNotFoundError:  # not installed (e.g. running from a bare source tree)
+    __version__ = "0+unknown"

treebox/assets/container/Dockerfile

@@ -0,0 +1,103 @@
+FROM python:3.14.6-slim
+
+ARG TZ=UTC
+ARG USER_UID=1000
+ARG USER_GID=1000
+ARG USERNAME=agent
+ARG NODE_MAJOR=22
+ARG CODEX_CLI_VERSION=latest
+ARG CLAUDE_CODE_VERSION=latest
+ARG GIT_DELTA_VERSION=0.18.2
+
+ENV TZ="$TZ"
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates curl wget gnupg2 less git procps sudo fzf zsh man-db \
+    unzip zip tar gzip bzip2 xz-utils nano vim jq yq rsync ripgrep fd-find \
+    iptables ipset iproute2 dnsutils aggregate openssh-client socat \
+    gcc g++ make cmake pkg-config python3-dev python3-venv bubblewrap \
+  && curl -fsSL "https://deb.nodesource.com/setup_${NODE_MAJOR}.x" | bash - \
+  && mkdir -p -m 755 /etc/apt/keyrings \
+  && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+       | dd of=/etc/apt/keyrings/githubcli-archive-keyring.gpg \
+  && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+       > /etc/apt/sources.list.d/github-cli.list \
+  && apt-get update && apt-get install -y --no-install-recommends nodejs gh \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+RUN ARCH=$(dpkg --print-architecture) && \
+    wget -q "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+    dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+    rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+RUN ARCH=$(dpkg --print-architecture) && \
+    case "$ARCH" in \
+      amd64) AWS_ARCH=x86_64 ;; \
+      arm64) AWS_ARCH=aarch64 ;; \
+      *) echo "unsupported arch $ARCH" && exit 1 ;; \
+    esac && \
+    curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-${AWS_ARCH}.zip" -o /tmp/awscliv2.zip && \
+    unzip -q /tmp/awscliv2.zip -d /tmp && \
+    /tmp/aws/install && \
+    rm -rf /tmp/awscliv2.zip /tmp/aws
+
+RUN if ! getent group "${USER_GID}" >/dev/null; then groupadd --gid "${USER_GID}" "${USERNAME}"; fi && \
+    useradd -m -u "${USER_UID}" -g "${USER_GID}" -s /bin/zsh "${USERNAME}" && \
+    echo "${USERNAME} ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/${USERNAME}-firewall && \
+    chmod 0440 /etc/sudoers.d/${USERNAME}-firewall
+
+RUN mkdir -p /workspace /home/${USERNAME}/.codex /home/${USERNAME}/.claude /home/${USERNAME}/.aws /commandhistory && \
+    chown -R ${USERNAME}:${USER_GID} /workspace /home/${USERNAME} /commandhistory
+
+RUN echo "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+      >> /home/${USERNAME}/.bashrc && \
+    echo "export HISTFILE=/commandhistory/.zsh_history" \
+      >> /home/${USERNAME}/.zshrc && \
+    touch /commandhistory/.bash_history /commandhistory/.zsh_history && \
+    chown -R ${USERNAME}:${USER_GID} /commandhistory /home/${USERNAME}/.bashrc /home/${USERNAME}/.zshrc
+
+USER ${USERNAME}
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/home/${USERNAME}/.local/bin:${PATH}"
+
+USER root
+RUN npm install -g "@openai/codex@${CODEX_CLI_VERSION}" && codex --version
+
+USER ${USERNAME}
+RUN curl -fsSL https://claude.ai/install.sh | bash -s ${CLAUDE_CODE_VERSION} && claude --version
+
+USER root
+
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN npm install -g @playwright/cli playwright && \
+    mkdir -p /ms-playwright && \
+    npx playwright install-deps chromium && \
+    playwright-cli install-browser && \
+    chown -R ${USERNAME}:${USER_GID} /ms-playwright && \
+    chmod -R u+rwX,go+rX /ms-playwright && \
+    CHROMIUM_BIN="$(find /ms-playwright -type f -name chrome -path '*chromium-*' | head -1)" && \
+    if [ -z "$CHROMIUM_BIN" ]; then echo "treebox: no Chromium binary found under /ms-playwright" >&2; ls -R /ms-playwright >&2; exit 1; fi && \
+    mkdir -p /opt/google/chrome && \
+    ln -sfn "$CHROMIUM_BIN" /opt/google/chrome/chrome && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Setup hooks are baked into the image, never run from the mounted worktree, so a
+# boxed agent cannot edit what runs at container setup.
+COPY init-firewall.sh /usr/local/bin/init-firewall.sh
+COPY allowed-domains.sh /usr/local/share/allowed-domains.sh
+COPY post-create.sh /usr/local/bin/post-create.sh
+RUN chmod +x /usr/local/bin/init-firewall.sh /usr/local/bin/post-create.sh
+
+USER ${USERNAME}
+
+ENV SHELL=/bin/zsh
+ENV EDITOR=nano
+ENV VISUAL=nano
+ENV CODEX_HOME=/home/${USERNAME}/.codex
+ENV CLAUDE_CONFIG_DIR=/home/${USERNAME}/.claude
+ENV NODE_OPTIONS="--max-old-space-size=4096"
+
+WORKDIR /workspace

treebox/assets/container/allowed-domains.sh

@@ -0,0 +1,25 @@
+# shellcheck shell=bash
+# Domains allowed through the container firewall (sourced by init-firewall.sh).
+# shellcheck disable=SC2034  # consumed by init-firewall.sh after sourcing
+ALLOWED_DOMAINS=(
+  api.anthropic.com
+  sentry.io
+  statsig.anthropic.com
+  statsig.com
+
+  api.openai.com
+  chatgpt.com
+  auth.openai.com
+  cdn.openai.com
+
+  pypi.org
+  files.pythonhosted.org
+  pypi.python.org
+  astral.sh
+
+  registry.npmjs.org
+  nodejs.org
+  deb.nodesource.com
+
+  cdn.playwright.dev
+)

treebox/assets/container/container.json

@@ -0,0 +1,27 @@
+{
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "UTC",
+      "CODEX_CLI_VERSION": "latest",
+      "CLAUDE_CODE_VERSION": "latest"
+    }
+  },
+  "user": "agent",
+  "mounts": [
+    "type=volume,source=treebox-shellhistory-${workspaceName},target=/commandhistory"
+  ],
+  "env": {
+    "CODEX_HOME": "/home/agent/.codex",
+    "CLAUDE_CONFIG_DIR": "/home/agent/.claude",
+    "HTTP_PROXY": "",
+    "HTTPS_PROXY": "",
+    "ALL_PROXY": "",
+    "NO_PROXY": "",
+    "http_proxy": "",
+    "https_proxy": "",
+    "all_proxy": "",
+    "no_proxy": ""
+  },
+  "postCreate": "bash /usr/local/bin/post-create.sh"
+}

treebox/assets/container/firewall.json

@@ -0,0 +1,4 @@
+{
+  "runArgs": ["--cap-add=NET_ADMIN", "--cap-add=NET_RAW"],
+  "env": { "TREEBOX_FIREWALL": "1" }
+}

treebox/assets/container/init-firewall.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+# post-create.sh refuses to touch the (untrusted) workspace until this exists;
+# it is only ever created after a fully successful lockdown (see the end).
+READY_FLAG=/run/treebox-firewall-ready
+
+# The runner execs this BOTH at setup (so default-deny egress exists before any
+# workspace-derived code runs in post-create.sh) and on every container restart
+# (rules don't survive a restart). When this boot already locked down
+# successfully, skip the rebuild rather than tearing live rules down
+# mid-session. Requires the flag AND the live policy: policy DROP alone also
+# matches the fail_closed end state, and the flag alone could be stale if /run
+# survived a restart. Placed before the trap so a clean skip cannot trip it.
+if [[ -f "$READY_FLAG" ]] && iptables -S OUTPUT 2>/dev/null | grep -q '^-P OUTPUT DROP'; then
+  echo "Firewall already active; skipping reconfiguration."
+  exit 0
+fi
+# A rebuild is starting: whatever a previous boot left behind, the firewall is
+# not ready until this run completes.
+rm -f "$READY_FLAG"
+
+# Fail closed: if setup aborts for any reason, drop all traffic rather than
+# leaving the container's inherited default-ACCEPT policies in place.
+fail_closed() {
+  local status=$?
+  if [[ "$status" -ne 0 ]]; then
+    iptables -P INPUT DROP
+    iptables -P FORWARD DROP
+    iptables -P OUTPUT DROP
+    iptables -F
+    if ip6tables -L INPUT >/dev/null 2>&1; then
+      ip6tables -P INPUT DROP
+      ip6tables -P FORWARD DROP
+      ip6tables -P OUTPUT DROP
+      ip6tables -F
+    fi
+    echo "ERROR: firewall setup failed; all traffic dropped" >&2
+  fi
+}
+trap fail_closed EXIT
+
+DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
+DNS_SERVERS=$(awk '/^nameserver/ {print $2}' /etc/resolv.conf | grep -E '^[0-9]{1,3}(\.[0-9]{1,3}){3}$' || true)
+
+# Fetch everything that needs open egress before locking down.
+echo "Fetching GitHub IP ranges..."
+gh_ranges=$(curl -s https://api.github.com/meta)
+[[ -n "$gh_ranges" ]] || { echo "ERROR: Failed to fetch GitHub IP ranges"; exit 1; }
+echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null
+
+DOMAINS_FILE=/usr/local/share/allowed-domains.sh
+[[ -f "$DOMAINS_FILE" ]] || { echo "ERROR: $DOMAINS_FILE missing"; exit 1; }
+# shellcheck source=src/treebox/assets/container/allowed-domains.sh
+source "$DOMAINS_FILE"
+[[ ${#ALLOWED_DOMAINS[@]} -gt 0 ]] || { echo "ERROR: ALLOWED_DOMAINS is empty"; exit 1; }
+
+# Default-deny before any rules are rebuilt: flushing alone would leave the
+# inherited ACCEPT policies in place, so an abort mid-setup would fail open.
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# The allowlist is IPv4-only, so IPv6 would bypass it entirely: drop all
+# IPv6 traffic except loopback.
+if ip6tables -L INPUT >/dev/null 2>&1; then
+  ip6tables -P INPUT DROP
+  ip6tables -P FORWARD DROP
+  ip6tables -P OUTPUT DROP
+  ip6tables -F
+  ip6tables -X
+  ip6tables -A INPUT  -i lo -j ACCEPT
+  ip6tables -A OUTPUT -o lo -j ACCEPT
+else
+  echo "WARN: ip6tables unavailable; assuming no IPv6 stack"
+fi
+
+if [[ -n "$DOCKER_DNS_RULES" ]]; then
+  iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+  iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+  echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
+fi
+
+iptables -A INPUT  -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+iptables -A INPUT  -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# DNS only to the configured resolvers; docker's embedded resolver
+# (127.0.0.11) is covered by the restored NAT rules plus the loopback allow.
+while read -r resolver; do
+  [[ -n "$resolver" ]] || continue
+  iptables -A OUTPUT -p udp --dport 53 -d "$resolver" -j ACCEPT
+  iptables -A OUTPUT -p tcp --dport 53 -d "$resolver" -j ACCEPT
+done <<< "$DNS_SERVERS"
+
+ipset create allowed-domains hash:net
+
+while read -r cidr; do
+  [[ "$cidr" =~ ^[0-9]{1,3}(\.[0-9]{1,3}){3}/[0-9]{1,2}$ ]] || { echo "ERROR: Invalid GitHub CIDR: $cidr"; exit 1; }
+  ipset add -exist allowed-domains "$cidr"
+done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q)
+
+for domain in "${ALLOWED_DOMAINS[@]}"; do
+  echo "Resolving $domain..."
+  ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+  if [[ -z "$ips" ]]; then
+    echo "WARN: Failed to resolve $domain; skipping"
+    continue
+  fi
+  while read -r ip; do
+    [[ "$ip" =~ ^[0-9]{1,3}(\.[0-9]{1,3}){3}$ ]] || { echo "ERROR: Invalid DNS IP for $domain: $ip"; exit 1; }
+    ipset add -exist allowed-domains "$ip"
+  done < <(echo "$ips")
+done
+
+HOST_IP=$(ip route | awk '/default/ {print $3; exit}')
+[[ -n "$HOST_IP" ]] || { echo "ERROR: Failed to detect host IP"; exit 1; }
+iptables -A OUTPUT -d "$HOST_IP" -j ACCEPT
+
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
+
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+  echo "ERROR: Firewall verification failed - reached https://example.com"
+  exit 1
+fi
+curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1 || {
+  echo "ERROR: Firewall verification failed - cannot reach api.github.com"
+  exit 1
+}
+
+touch "$READY_FLAG"
+echo "Firewall configuration complete"

treebox/assets/container/post-create.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+set -euo pipefail
+
+# Baked into the image at /usr/local/bin, so the workspace can't be derived from
+# this script's location. The runner execs it with the workspace as the working
+# dir; $1 overrides that when given.
+WS="${1:-${PWD}}"
+
+# Egress lockdown gate: when the operator enabled the firewall, refuse to run
+# anything derived from the untrusted workspace (uv sync executes the repo's
+# build backend) until init-firewall.sh has established default-deny egress.
+# The runner execs the firewall first; this fails closed if that ordering is
+# ever lost.
+if [[ "${TREEBOX_FIREWALL:-}" == "1" && ! -f /run/treebox-firewall-ready ]]; then
+  echo "ERROR: firewall enabled but not initialized; refusing to run workspace setup." >&2
+  echo "       init-firewall.sh must complete before post-create.sh." >&2
+  exit 1
+fi
+
+if [[ -f "$WS/pyproject.toml" ]] && command -v uv >/dev/null 2>&1; then
+  echo "Running uv sync..."
+  (cd "$WS" && uv sync)
+elif [[ ! -d "$WS/.venv" ]] && { [[ -f "$WS/requirements.txt" ]] || [[ -f "$WS/setup.py" ]]; }; then
+  echo "Creating Python virtual environment..."
+  (cd "$WS" && uv venv .venv)
+  if [[ -f "$WS/requirements.txt" ]]; then
+    echo "Installing requirements.txt..."
+    (cd "$WS" && uv pip install -r requirements.txt)
+  fi
+  if [[ -f "$WS/setup.py" ]]; then
+    echo "Installing project in editable mode..."
+    (cd "$WS" && uv pip install -e .)
+  fi
+fi
+
+if [[ -d "$HOME/.ssh" ]]; then
+  chmod 700 "$HOME/.ssh" 2>/dev/null || true
+  chmod 600 "$HOME/.ssh"/* 2>/dev/null || true
+  chmod 644 "$HOME/.ssh"/*.pub 2>/dev/null || true
+  chmod 644 "$HOME/.ssh/known_hosts" 2>/dev/null || true
+fi
+
+if command -v playwright-cli >/dev/null 2>&1; then
+  echo "Installing playwright skills..."
+  (cd "$WS" && playwright-cli install --skills)
+fi
+
+echo "post-create.sh done."

treebox/assets/pre-push

@@ -0,0 +1,27 @@
+#!/bin/sh
+# treebox pre-push guard: placeholder branches are un-pushable by design.
+#
+# Installed per-worktree by `treebox create` (a private core.hooksPath — never
+# the shared repo hooks). The treebox/ prefix marks an auto-generated name; a
+# PR must never carry one. Renaming clears the guard — use a conventional
+# branch name (feature/<name>, fix/<name>, chore/<name>, …):
+#   git branch -m <type>/<short-name>
+# `git push --no-verify` remains the deliberate human escape hatch.
+status=0
+while read -r local_ref _local_oid _remote_ref _remote_oid; do
+    case "$local_ref" in
+    refs/heads/treebox/*)
+        branch="${local_ref#refs/heads/}"
+        {
+            printf '%s\n' "✗ treebox: refusing to push placeholder branch '$branch'."
+            printf '%s\n' "  ↳ name this work first, then push again:  git branch -m <type>/<short-name>"
+            printf '%s\n' "  ↳ we use conventional-commits style branch names — pick the type that fits"
+            printf '%s\n' "    the change: feature/user-auth, fix/login-race, chore/bump-deps,"
+            printf '%s\n' "    docs/api-guide, refactor/db-layer, test/flaky-suite, …"
+            printf '%s\n' "  ↳ the treebox/ prefix marks auto-generated names; PRs should never carry them."
+        } >&2
+        status=1
+        ;;
+    esac
+done
+exit $status

treebox/assets.py

@@ -0,0 +1,69 @@
+"""Resolve the sandbox container template directory.
+
+The sandbox template is operator-owned and never read from the target repo: a
+repo you don't trust must not define the container it runs in (mounts, runArgs,
+and env can all reach the host). The agent runs *inside* the box; the config
+that defines the box lives where a boxed agent cannot see or edit it.
+
+Templates are selectable by name so devs can keep several sandbox shapes
+(``python``, ``node``, a locked-down vs. a permissive one) side by side and pick
+one per run with ``--template``. Resolution order for ``name``:
+
+1. ``$TREEBOX_TEMPLATE_DIR`` (explicit dir; wins for any name)
+2. ``$XDG_CONFIG_HOME/treebox/templates/<name>``
+3. the bundled package data (``assets/container``) — only for the default.
+
+A named template that resolves to none of these is an error, not a silent
+fallback to the default: asking for ``--template hardened`` and quietly getting
+the stock box would defeat the point.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib import resources
+from pathlib import Path
+
+DEFAULT_TEMPLATE = "default"
+
+# The container definition the docker runner renders and runs. Its schema is
+# treebox-owned: build.{dockerfile,args}, user, mounts, env, runArgs, postCreate.
+CONFIG_FILE = "container.json"
+
+TEMPLATE_FILES = (
+    CONFIG_FILE,
+    "Dockerfile",
+    "post-create.sh",
+    "init-firewall.sh",
+    "allowed-domains.sh",
+)
+FIREWALL_FILE = "firewall.json"
+
+
+def _user_templates_root() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base).expanduser() / "treebox" / "templates"
+
+
+def template_dir(name: str = DEFAULT_TEMPLATE) -> Path:
+    """Resolve the operator-owned template directory for ``name``.
+
+    Never reads from the target repo — see the module docstring for why.
+    """
+    explicit = os.environ.get("TREEBOX_TEMPLATE_DIR")
+    if explicit:
+        return Path(explicit).expanduser()
+
+    user = _user_templates_root() / name
+    if user.is_dir():
+        return user
+
+    if name == DEFAULT_TEMPLATE:
+        with resources.as_file(resources.files("treebox") / "assets" / "container") as p:
+            return Path(p)
+
+    raise RuntimeError(
+        f"No template named '{name}'. Create one at {user} "
+        f"(or point $TREEBOX_TEMPLATE_DIR at a template dir). "
+        f"'{DEFAULT_TEMPLATE}' is the only built-in template."
+    )