trusty-cage 0.2.0__tar.gz

trusty_cage-0.2.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(source:*)"
+    ],
+    "additionalDirectories": [
+      "/Users/areese/.dotfiles"
+    ]
+  }
+}

trusty_cage-0.2.0/.env.example

@@ -0,0 +1,17 @@
+# trusty-cage user configuration
+#
+# IMPORTANT: Do NOT use this file at the project root.
+# Copy it to ~/.trusty-cage/.env — that's where trusty-cage reads it from.
+#
+#   mkdir -p ~/.trusty-cage
+#   cp .env.example ~/.trusty-cage/.env
+#   # then edit ~/.trusty-cage/.env with your values
+#
+# This file lives at ~/.trusty-cage/.env so your config persists across
+# installs and works regardless of where you cloned the repo.
+
+TRUSTY_CAGE_DOTFILES_REPO=https://github.com/youruser/dotfiles
+TRUSTY_CAGE_PYTHON_VERSION=3.12
+TRUSTY_CAGE_DEFAULT_SHELL=zsh
+TRUSTY_CAGE_DEFAULT_AUTH_MODE=api_key
+TRUSTY_CAGE_TMUX_PREFIX=C-a

trusty_cage-0.2.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environment
+venv/
+
+# Environment / secrets
+.env
+set_creds.sh
+
+# IDE
+.idea/
+.vscode/
+.zed/
+
+# OS
+.DS_Store
+
+# pytest
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# Docker image export artifacts
+info/
+isolated-dev-*/
+trusty-cage:*/
+
+# trusty-cage working files
+TODO.md

trusty_cage-0.2.0/CLAUDE.md

@@ -0,0 +1,128 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**trusty-cage** is a host-side Python CLI tool that creates fully isolated, persistent Docker-based development environments on macOS (via OrbStack). Each environment is scoped to a single git repo, contains no git credentials, and provides an interactive dev experience (tmux + Neovim/LazyVim + Claude Code) inside a container. Work is exported back to the host for git operations.
+
+v1 is feature-complete. The archived v1 specification is at `docs/v1-spec.md`. Planned enhancements are in `v2-spec.md`.
+
+## Build & Development
+
+```bash
+# Setup
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+
+# Run
+trusty-cage --help
+
+# Lint & format
+ruff format .
+ruff check --fix .
+
+# Tests
+pytest
+pytest tests/test_foo.py              # single file
+pytest tests/test_foo.py::test_bar    # single test
+
+# Build & publish (requires build + twine in dev deps)
+make build          # Build wheel and sdist
+make publish-test   # Upload to TestPyPI
+make publish        # Upload to PyPI
+make help           # Show all targets
+```
+
+## Architecture
+
+### CLI Framework
+
+- **Typer** for CLI with **Rich** for terminal output
+- All Docker operations via **subprocess calls to `docker` CLI** (not the Docker Python SDK)
+
+### CLI Commands
+
+The CLI is available as `trusty-cage` or the short alias `tc`.
+
+| Command | Purpose |
+|---|---|
+| `init [--force]` | Create config directory and default `.env` file |
+| `create <git-repo-url> [--name] [--no-attach]` | Clone repo, build image, create container+volume, copy files in, init local git, apply dotfiles, attach |
+| `attach <name>` | Start container if stopped, apply iptables, create/attach tmux session |
+| `stop <name>` | Stop container (preserves volume) |
+| `list` | Show all environments with status, date, repo URL |
+| `export <name>` | Copy container files → host clone via rsync (preserving host `.git/`) |
+| `destroy <name>` | Remove container + volume (keeps host clone) |
+| `rebuild-image` | Force rebuild Docker image |
+
+### Host File Layout
+
+```
+~/.trusty-cage/
+  .env                 # User config (created by `trusty-cage init`)
+  image.sha            # SHA of Dockerfile for rebuild detection
+  envs/<name>/
+    meta.json          # Source of truth: repo_url, created_at, volume_name, host_clone_path, auth_mode
+    repo/              # Full host clone with remotes (for export)
+```
+
+### Container Setup
+
+- Base: `ubuntu:24.04` (ARM64)
+- Non-root user: `trustycage` (UID 1000), home `/home/trustycage`
+- Working directory: `/home/trustycage/project` (Docker named volume: `isolated-dev-<name>`)
+- No bind mounts, no SSH keys, no git credentials, no `.netrc`, no `~/.config/gh`
+- `ANTHROPIC_API_KEY` injected at runtime via `docker exec -e` (never on disk)
+- Dotfiles: cloned on host → `docker cp` into container (`.git/` stripped) → run install script if present
+
+### Network Policy
+
+Applied via `init-network.sh` at attach time (run as root, then drops to `trustycage`). Must be idempotent (use `iptables -C` before adding rules).
+
+- **Blocked**: Port 22 (SSH) to all hosts; `hub.docker.com` / `registry-1.docker.io`
+- **Allowed**: Everything else (HTTPS git, packages, web, DNS)
+- Primary protection is **credential absence**, not network blocking
+
+### Authentication Modes
+
+Chosen at `create` time, stored in `meta.json`:
+
+- **api_key**: Reads host env var at attach time, injected via `docker exec -e`
+- **subscription**: Copies `~/.claude/` into container via `docker cp` at create time; persists in volume
+
+## Code Conventions
+
+### Imports
+- All imports must be at the top of the file — no inline or lazy imports inside functions
+- This applies to all Python files in the project
+
+## Git Workflow
+
+- Work happens on feature branches off `develop`
+- Merges to `main` are done via PR on GitHub — never merge locally
+- Push the feature/develop branch and open a PR
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`
+
+- **MAJOR** — breaking changes (renamed commands, changed config format, dropped features)
+- **MINOR** — new features, backwards-compatible (new commands, new config options)
+- **PATCH** — bug fixes, docs-only changes, no behavior change
+
+Version is set in two places (keep in sync):
+- `pyproject.toml` → `version`
+- `src/trusty_cage/__init__.py` → `__version__`
+
+**When to prompt about version bumps:** Before committing work that adds new features (minor bump) or fixes bugs (patch bump), suggest the appropriate version increment to the user. Don't bump automatically — ask first.
+
+## Key Design Constraints
+
+- `meta.json` is the source of truth for environment state — never infer from Docker state alone
+- All operations should be **idempotent** where possible
+- The tool must **never** run `git push` or configure git credentials
+- Container's local git repo has no remotes — Claude Code uses git locally only
+- Export uses rsync to overlay container files onto host clone, preserving host's `.git/`
+- Published on PyPI as `trusty-cage` — installable via `pip install trusty-cage` or `pipx install trusty-cage`

trusty_cage-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Reese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trusty_cage-0.2.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: help build publish publish-test lint format test clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
+
+build: clean ## Build wheel and sdist
+	python -m build
+
+publish: build ## Build and upload to PyPI
+	. ./set_creds.sh && twine upload dist/*
+
+publish-test: build ## Build and upload to TestPyPI
+	. ./set_creds.sh && twine upload --repository testpypi dist/*
+
+lint: ## Run ruff check
+	ruff check .
+
+format: ## Run ruff format
+	ruff format .
+
+test: ## Run pytest
+	pytest -q
+
+clean: ## Remove build artifacts
+	rm -rf dist/ build/ src/*.egg-info

trusty_cage-0.2.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: trusty-cage
+Version: 0.2.0
+Summary: Isolated Docker-based development environments for AI coding agents
+Project-URL: Homepage, https://github.com/areese801/trusty-cage
+Project-URL: Repository, https://github.com/areese801/trusty-cage
+Project-URL: Issues, https://github.com/areese801/trusty-cage/issues
+Author: Adam Reese
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,containers,development,docker,isolation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# trusty-cage
+
+Isolated Docker-based development environments for AI coding agents. Run Claude Code (or any agent) with full autonomy inside a disposable container — no risk to your host machine, no credentials exposed, no accidental pushes.
+
+## Installation
+
+```bash
+pip install trusty-cage
+```
+
+Or with [pipx](https://pipx.pypa.io/) for isolated CLI installs:
+
+```bash
+pipx install trusty-cage
+```
+
+`tc` is available as a shorthand for `trusty-cage` (e.g. `tc create ...`, `tc attach ...`).
+
+## Quick Start
+
+```bash
+# One-time setup: create config directory and default .env file
+trusty-cage init
+
+# Create an environment from any git repo
+trusty-cage create https://github.com/octocat/Hello-World
+
+# You're now inside a tmux session (prefix: Ctrl-a) with:
+#   Left pane (60%)  — Neovim at the project root
+#   Top-right pane   — Claude Code running with --dangerously-skip-permissions
+#   Bottom-right pane — plain shell
+
+# Switch panes with Ctrl-a <arrow>, detach with Ctrl-a d
+
+# When done, export your work back to the host:
+trusty-cage export hello-world
+
+# Review and push from the host clone:
+cd ~/.trusty-cage/envs/hello-world/repo/
+git diff
+git add -A && git commit -m "work from trusty-cage"
+git push
+```
+
+## Example: Hello World
+
+```bash
+# Create (environment name is derived as lowercase: "hello-world")
+trusty-cage create https://github.com/octocat/Hello-World --no-attach
+
+# Verify
+trusty-cage list
+docker ps -a | grep isolated-dev
+
+# Attach — drops you into tmux inside the container
+trusty-cage attach hello-world
+
+# Inside the container:
+#   Ctrl-a <arrow>    — switch tmux panes
+#   git remote -v     — empty (no remotes, by design)
+#   curl example.com  — works (outbound web allowed)
+#   Ctrl-a d          — detach
+
+# Export work back to host
+trusty-cage export hello-world
+
+# Clean up
+trusty-cage destroy hello-world
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `trusty-cage init [--force]` | Create config directory and default `.env` file |
+| `trusty-cage create <url> [--name NAME] [--no-attach]` | Create a new environment from a git repo |
+| `trusty-cage attach <name>` | Attach to an existing environment |
+| `trusty-cage stop <name>` | Stop a container (preserves work) |
+| `trusty-cage list` | List all environments with status |
+| `trusty-cage export <name>` | Copy work back to host clone |
+| `trusty-cage destroy <name>` | Remove container and volume (keeps host clone) |
+| `trusty-cage rebuild-image` | Force rebuild the Docker image |
+
+## Configuration
+
+Configuration is resolved in order: CLI flags > environment variables > `~/.trusty-cage/.env` > defaults.
+
+| Variable | Default | Description |
+|---|---|---|
+| `TRUSTY_CAGE_DOTFILES_REPO` | *(empty)* | HTTPS URL of dotfiles repo to clone into containers |
+| `TRUSTY_CAGE_PYTHON_VERSION` | `3.12` | Python version installed via pyenv |
+| `TRUSTY_CAGE_DEFAULT_SHELL` | `zsh` | Default shell inside the container |
+| `TRUSTY_CAGE_DEFAULT_AUTH_MODE` | `api_key` | Auth mode: `api_key` or `subscription` |
+| `TRUSTY_CAGE_TMUX_PREFIX` | `C-a` | tmux prefix key inside containers (default `Ctrl-a` to avoid conflict with host `Ctrl-b`) |
+| `ANTHROPIC_API_KEY` | *(none)* | API key for Claude Code (required for `api_key` auth mode) |
+
+Run `trusty-cage init` to create `~/.trusty-cage/.env` with a commented template you can customize.
+
+## Dotfiles
+
+If you set `TRUSTY_CAGE_DOTFILES_REPO`, your dotfiles are automatically applied to every new container at `create` time. The repo is cloned on the host, `.git/` is stripped, and the files are copied into the container's home directory. If an install script is found (`install.sh`, `setup.sh`, `bootstrap.sh`, etc.), it runs automatically. GNU Stow layouts are detected and handled (files are copied from `common/` if present).
+
+This means your shell config, tmux settings, Neovim config, aliases, and other personalizations carry over — the container feels like your own machine.
+
+**Without dotfiles**, the container ships with sensible defaults: oh-my-zsh (robbyrussell theme), LazyVim starter config, pyenv on PATH, and `vim`/`vi` aliased to `nvim`. Everything works out of the box, just without your personal customizations.
+
+## Authentication
+
+Chosen at `create` time:
+
+- **api_key** — Reads `ANTHROPIC_API_KEY` from your host shell at attach time. Injected via `docker exec -e`, never written to disk.
+- **subscription** — Copies `~/.claude/` credentials into the container at create time. Persists in the volume.
+
+## Security Model
+
+The container is the blast radius. If an agent does something destructive, your host is unaffected.
+
+**What agents can do inside:**
+- Clone/fetch public repos over HTTPS
+- Browse the web, read docs, hit public APIs
+- Install packages (pip, apt, npm)
+- Full read/write access to the project directory
+
+**What agents cannot do:**
+- Push to any git remote (no credentials present)
+- Use SSH (port 22 blocked)
+- Pull Docker images from Docker Hub (blocked)
+- Access any host files (no bind mounts)
+
+Protection is enforced by **credential absence**, not network blocking. The container has no SSH keys, no `.netrc`, no `GH_TOKEN`, no git credential helper.
+
+## Requirements
+
+- macOS with OrbStack or Docker Desktop
+- Python 3.11+
+- Git
+- rsync (pre-installed on macOS; used by `export`)
+
+## Development
+
+```bash
+git clone https://github.com/areese801/trusty-cage.git
+cd trusty-cage
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+
+# Available make targets
+make help
+```
+
+## License
+
+MIT

trusty_cage-0.2.0/README.md

@@ -0,0 +1,154 @@
+# trusty-cage
+
+Isolated Docker-based development environments for AI coding agents. Run Claude Code (or any agent) with full autonomy inside a disposable container — no risk to your host machine, no credentials exposed, no accidental pushes.
+
+## Installation
+
+```bash
+pip install trusty-cage
+```
+
+Or with [pipx](https://pipx.pypa.io/) for isolated CLI installs:
+
+```bash
+pipx install trusty-cage
+```
+
+`tc` is available as a shorthand for `trusty-cage` (e.g. `tc create ...`, `tc attach ...`).
+
+## Quick Start
+
+```bash
+# One-time setup: create config directory and default .env file
+trusty-cage init
+
+# Create an environment from any git repo
+trusty-cage create https://github.com/octocat/Hello-World
+
+# You're now inside a tmux session (prefix: Ctrl-a) with:
+#   Left pane (60%)  — Neovim at the project root
+#   Top-right pane   — Claude Code running with --dangerously-skip-permissions
+#   Bottom-right pane — plain shell
+
+# Switch panes with Ctrl-a <arrow>, detach with Ctrl-a d
+
+# When done, export your work back to the host:
+trusty-cage export hello-world
+
+# Review and push from the host clone:
+cd ~/.trusty-cage/envs/hello-world/repo/
+git diff
+git add -A && git commit -m "work from trusty-cage"
+git push
+```
+
+## Example: Hello World
+
+```bash
+# Create (environment name is derived as lowercase: "hello-world")
+trusty-cage create https://github.com/octocat/Hello-World --no-attach
+
+# Verify
+trusty-cage list
+docker ps -a | grep isolated-dev
+
+# Attach — drops you into tmux inside the container
+trusty-cage attach hello-world
+
+# Inside the container:
+#   Ctrl-a <arrow>    — switch tmux panes
+#   git remote -v     — empty (no remotes, by design)
+#   curl example.com  — works (outbound web allowed)
+#   Ctrl-a d          — detach
+
+# Export work back to host
+trusty-cage export hello-world
+
+# Clean up
+trusty-cage destroy hello-world
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `trusty-cage init [--force]` | Create config directory and default `.env` file |
+| `trusty-cage create <url> [--name NAME] [--no-attach]` | Create a new environment from a git repo |
+| `trusty-cage attach <name>` | Attach to an existing environment |
+| `trusty-cage stop <name>` | Stop a container (preserves work) |
+| `trusty-cage list` | List all environments with status |
+| `trusty-cage export <name>` | Copy work back to host clone |
+| `trusty-cage destroy <name>` | Remove container and volume (keeps host clone) |
+| `trusty-cage rebuild-image` | Force rebuild the Docker image |
+
+## Configuration
+
+Configuration is resolved in order: CLI flags > environment variables > `~/.trusty-cage/.env` > defaults.
+
+| Variable | Default | Description |
+|---|---|---|
+| `TRUSTY_CAGE_DOTFILES_REPO` | *(empty)* | HTTPS URL of dotfiles repo to clone into containers |
+| `TRUSTY_CAGE_PYTHON_VERSION` | `3.12` | Python version installed via pyenv |
+| `TRUSTY_CAGE_DEFAULT_SHELL` | `zsh` | Default shell inside the container |
+| `TRUSTY_CAGE_DEFAULT_AUTH_MODE` | `api_key` | Auth mode: `api_key` or `subscription` |
+| `TRUSTY_CAGE_TMUX_PREFIX` | `C-a` | tmux prefix key inside containers (default `Ctrl-a` to avoid conflict with host `Ctrl-b`) |
+| `ANTHROPIC_API_KEY` | *(none)* | API key for Claude Code (required for `api_key` auth mode) |
+
+Run `trusty-cage init` to create `~/.trusty-cage/.env` with a commented template you can customize.
+
+## Dotfiles
+
+If you set `TRUSTY_CAGE_DOTFILES_REPO`, your dotfiles are automatically applied to every new container at `create` time. The repo is cloned on the host, `.git/` is stripped, and the files are copied into the container's home directory. If an install script is found (`install.sh`, `setup.sh`, `bootstrap.sh`, etc.), it runs automatically. GNU Stow layouts are detected and handled (files are copied from `common/` if present).
+
+This means your shell config, tmux settings, Neovim config, aliases, and other personalizations carry over — the container feels like your own machine.
+
+**Without dotfiles**, the container ships with sensible defaults: oh-my-zsh (robbyrussell theme), LazyVim starter config, pyenv on PATH, and `vim`/`vi` aliased to `nvim`. Everything works out of the box, just without your personal customizations.
+
+## Authentication
+
+Chosen at `create` time:
+
+- **api_key** — Reads `ANTHROPIC_API_KEY` from your host shell at attach time. Injected via `docker exec -e`, never written to disk.
+- **subscription** — Copies `~/.claude/` credentials into the container at create time. Persists in the volume.
+
+## Security Model
+
+The container is the blast radius. If an agent does something destructive, your host is unaffected.
+
+**What agents can do inside:**
+- Clone/fetch public repos over HTTPS
+- Browse the web, read docs, hit public APIs
+- Install packages (pip, apt, npm)
+- Full read/write access to the project directory
+
+**What agents cannot do:**
+- Push to any git remote (no credentials present)
+- Use SSH (port 22 blocked)
+- Pull Docker images from Docker Hub (blocked)
+- Access any host files (no bind mounts)
+
+Protection is enforced by **credential absence**, not network blocking. The container has no SSH keys, no `.netrc`, no `GH_TOKEN`, no git credential helper.
+
+## Requirements
+
+- macOS with OrbStack or Docker Desktop
+- Python 3.11+
+- Git
+- rsync (pre-installed on macOS; used by `export`)
+
+## Development
+
+```bash
+git clone https://github.com/areese801/trusty-cage.git
+cd trusty-cage
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+
+# Available make targets
+make help
+```
+
+## License
+
+MIT