Install

treebox runs on Python 3.11+ and installs like any other PyPI CLI. The recommended path is uv, which also fetches a managed interpreter — so the host Python doesn't matter.

One line

curl -fsSL https://raw.githubusercontent.com/Seth-Peters/treebox/main/install.sh | sh

No uv?

The script stops and tells you how to get it — it won't install a package manager behind your back. Install uv first, or re-run with TREEBOX_AUTO_UV=1 to let the script do it.

With a package manager

uvpipxfrom the repo

uv tool install treebox

pipx install treebox          # needs Python >=3.11 on the host

uv tool install git+https://github.com/Seth-Peters/treebox

What each isolation mode needs

Requirement	host	docker
git	✓	✓
Subscription login (~/.claude / ~/.codex)	✓	✓
Host agent CLI on PATH (claude / codex)	✓	— (template-provided)
docker	—	✓
Non-root user (not uid 0)	-	✓

That's the whole table: docker isolation speaks plain docker build / docker run / docker exec, so there is no Node.js and no dev-container CLI to install. See sandbox build requirements for network access and builder compatibility. The default template installs the agent CLIs in the image; the host supplies scoped subscription-login copies. The worktree and its git dir are mounted at their host paths, so in-container git just works — with no special git version requirement.

Host isolation launches against your live ~/.claude / ~/.codex subscription login. Docker isolation stages scoped copies of those login files and never mounts the live dirs. On macOS, Claude Code keeps its login in the Keychain (your user's Claude Code-credentials item), not in ~/.claude/.credentials.json: when that file is absent, treebox reads the Keychain item and stages it as the sandbox's .credentials.json. If macOS asks whether security may read the item, allow it; a request that is denied or not answered within 30 seconds counts as no login. The sandbox template docker isolation provisions is pinned to CPython 3.14.6, independent of whatever runs treebox itself.

Docker isolation requires a non-root user (uid other than 0), even with --no-firewall. The default sandbox template gives the agent your uid. A root agent could remove its own firewall rules.

For Docker isolation, create and enter check the uid before provisioning, including with --print or --json. They refuse uid 0 with RUNNING_AS_ROOT. A refused create makes no worktree, branch, or image. A refused enter leaves the existing worktree in place. doctor --isolation docker reports a failed isolation check and exits with code 1.

On Linux with a docker group, create a non-root user that can reach the Docker daemon:

useradd --create-home --groups docker treebox

Then run treebox as that user, for example with su - treebox. Host isolation still works as root.

Verify

$ treebox doctor

  ● doctor   isolation: host

    ✓ git               2.47.3
    ✓ repo              ~/code/myapp
    ✓ uid/gid           1000:1000
    ✓ login: claude     ~/.claude
    ✓ login: codex      ~/.codex
    ✓ .env              ~/code/myapp/.env
    ✓ git auth          authenticated · fresh fetch will succeed
    ✓ isolation: host   no container dependencies

  ✓ everything looks good

doctor checks the exact things create will need — git, agent logins, credentials for the required origin fetch — and prints an advisory with the fix when something is off. A missing .env is only noted as optional, never a failure. Pass --isolation docker to check the Docker daemon too.

Updating

When a new version is released to PyPI, upgrade with the same tool you used to install:

uvpipxinstaller

uv tool upgrade treebox

pipx upgrade treebox

curl -fsSL https://raw.githubusercontent.com/Seth-Peters/treebox/main/install.sh | sh

The project uses normal PyPI versions derived from release tags, so users receive updates when you publish a newer version and they run their package manager's upgrade command.

Installer overrides

The install.sh script reads a few environment variables:

Variable	Effect
TREEBOX_INSTALL_SPEC	What to install — a PyPI spec (treebox==0.4.0) or a git+https://… URL.
TREEBOX_TESTPYPI	Set to 1 to install from TestPyPI (dependencies still come from PyPI).
TREEBOX_AUTO_UV	Set to 1 to auto-install uv if it's missing (default: fail loudly).

Developing treebox itself

git clone https://github.com/Seth-Peters/treebox && cd treebox
uv run treebox ...                    # run the CLI from the working tree
uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
uv run --extra dev python -m pytest   # unit + integration suite
uv run --extra dev mypy               # strict type check
./scripts/validate.sh                 # full gate: lint + typecheck + shell assets + tests + snapshots + smoke