secure_agent_envs/CLAUDE.md

# CLAUDE.md

## Project Memory

This project uses three documentation files as persistent memory. **You must keep these files up to date when making changes:**

| File | Purpose | Update When |
|------|---------|-------------|
| `CLAUDE.md` | Technical context for Claude Code sessions | Adding new patterns, conventions, or implementation details |
| `CHANGELOG.md` | Version history following Keep a Changelog format | Every commit (add entry, bump version) |
| `README.md` | User-facing documentation | Changing user-visible behavior, adding features, or modifying usage |

### Versioning Rules

- Use semantic versioning (MAJOR.MINOR.PATCH)
- Increment PATCH for bug fixes and minor updates
- Increment MINOR for new features and enhancements
- Increment MAJOR for breaking changes
- Tag every commit with its version: `git tag -a vX.Y.Z -m "Description"`

## Project Overview

This repository provides scripts for creating isolated development sandboxes for Claude Code on macOS (OrbStack) and Windows (Hyper-V). Both platforms offer full VM isolation for safely running AI coding assistants with elevated permissions.

**Supported platforms:**
- **macOS**: OrbStack VMs (ARM64 Apple Silicon)
- **Windows**: Hyper-V VMs (maximum security, stronger than WSL2)

## Repository Structure

```
setup_env.sh            - macOS script (OrbStack host mode + Linux VM provisioning)
setup_env_windows.ps1   - Windows script (Hyper-V with cloud-init)
WINDOWS_PLAN.md         - Windows implementation plan and security rationale
config.env.example      - Example credentials file
config.env              - User credentials (gitignored, created on first run)
.gitignore              - Ignores config.env
README.md               - User-facing documentation
CHANGELOG.md            - Version history (Keep a Changelog format)
CLAUDE.md               - This file (context for Claude Code sessions)
```

## How the Script Works

The script has two modes, detected via `uname -s`:

- **Darwin (macOS)**: Orchestrator mode. Checks for OrbStack, reads/creates `config.env`, creates a VM, copies itself in, runs itself inside the VM with `--non-interactive`.
- **Linux (VM)**: Provisioning mode. Installs all tools, configures PostgreSQL, sets up VNC, installs Claude Code plugins.

This means `./setup_env.sh my-vm` on macOS does everything end-to-end.

## Key Technical Details

- **Target environment**: OrbStack Ubuntu VM on macOS Apple Silicon (ARM64)
- **Version manager**: mise (manages Node.js, Erlang, Elixir)
- **Versions**: All tools use latest by default. Erlang/Elixir versions can be configured at the top of `setup_env.sh` (`ERLANG_VERSION`, `ELIXIR_VERSION`) - set to "latest" or pin to specific versions
- **PostgreSQL auth**: Peer for local socket, scram-sha-256 for all TCP connections (localhost and network)
- **Browser**: Chromium (no Chrome ARM64 Linux builds exist), symlinked to `google-chrome`
- **VNC**: TigerVNC + XFCE on display :1 (port 5901), controlled via `vnc-start`/`vnc-stop` helpers in `~/bin`
- **Shared credentials**: `config.env` stores git name/email only; VNC password is prompted each time (never stored)

## Working on This Project

### Editing setup_env.sh

- The macOS host-mode block is at the top (inside the `if [[ "$(uname -s)" == "Darwin" ]]` block)
- The Linux VM-mode block is everything after that conditional
- Version numbers are defined as variables at the top (`ERLANG_VERSION`, `ELIXIR_VERSION`)
- All installation steps must be idempotent (safe to run multiple times)
- Use `log_info`, `log_warn`, `log_error` helpers for output
- New apt packages go in the base dependencies section
- New Claude plugins go in the appropriate array (`ANTHROPIC_PLUGINS` or `SUPERPOWERS_PLUGINS`)
- Redirect verbose output to `$LOG_FILE`, show only meaningful progress to the user
- The `LOG_FILE` variable is only set in VM mode (not available in macOS host mode)
- Each optional component is wrapped in `prompt_install "Name" "Description"` — this handles both interactive prompts and `--yes`/`--non-interactive` auto-accept
- Track dependency flags (`INSTALLED_NODE`, `INSTALLED_CHROMIUM`) to skip dependent components gracefully

### Script Conventions

- `set -euo pipefail` is enforced - handle potential failures with `|| true` or explicit checks
- Use `command_exists` to check for already-installed tools
- Use `apt-get` (not `apt`) for scripting reliability
- Quote all variable expansions
- Use `find` for PostgreSQL config paths (version-agnostic)
- The `--non-interactive` flag is for VM mode (implies `--yes`); macOS mode always uses config.env
- `--yes`/`-y` accepts all components without prompting but still allows interactive credential entry
- `MISE_GLOBAL_CONFIG_FILE` and `MISE_CONFIG_DIR` are set to prevent OrbStack host-mount config pollution

### Security Patterns (macOS/Linux)

- **Input validation**: Use `validate_vm_name()`, `validate_vnc_password()`, `validate_safe_input()` for all user inputs
- **Safe config loading**: Use `load_config_safely()` which parses key=value pairs without shell execution (never `source`)
- **Credential passing**: Base64-encode values before passing to VM via `orb run` to prevent shell injection
- **Download helper**: Use `download_verified_binary()` for binary downloads (supports optional checksum verification)
- **Temp files**: Always use `mktemp` with restrictive permissions (`chmod 600`/`700`)
- **Symlinks**: Check with `[ ! -e path ]` (not `[ ! -L path ]`) to avoid overwriting existing files
- **Architecture detection**: Use `detect_architecture()` for portable binary downloads

### Editing setup_env_windows.ps1

- PowerShell script for Windows Hyper-V VM creation
- Uses Ubuntu cloud images with cloud-init for automated provisioning
- Supports ARM64 architecture detection for Windows on ARM
- Skip parameters: `-SkipVNC`, `-SkipPostgreSQL`, `-SkipOllama`, `-SkipPlaywright`
- ISO creation fallback chain: oscdimg → WSL genisoimage → IMAPI2 COM
- Log file created at `$env:TEMP\setup_env_windows_<timestamp>.log`

### Security Patterns (Windows)

- **Input validation**: Use `Test-GitName`, `Test-GitEmail`, `Test-VMPassword`, `Test-VNCPassword` for all user inputs
- **Config file security**: ACL set to owner-only before writing content (no race condition)
- **Config validation**: Loaded config.env values are re-validated to detect tampering
- **Checksum verification**: Ubuntu image verified against SHA256 checksums from Canonical
- **Cleanup on failure**: `Invoke-Cleanup` removes partial VM, disk, and ISO on errors
- **Hosts file backup**: Created before modification, removed on success, kept on failure
- **Cloud-init ISO**: Contains passwords in plaintext; user reminded to remove after first boot

### Testing

There are no automated tests. To test changes:

**macOS:**
1. Remove an existing test VM: `orb delete test-sandbox`
2. Run: `./setup_env.sh test-sandbox`
3. Verify provisioning completes
4. Run again to verify idempotency: `ssh test-sandbox@orb -- bash /tmp/setup_env.sh --non-interactive` (will need env vars)
5. Test VNC: `ssh test-sandbox@orb -- vnc-start`, then `open vnc://test-sandbox.orb.local:5901`
6. Clean up: `orb delete test-sandbox`

**Windows:**
1. Remove existing test VM: `Stop-VM -Name test-sandbox -Force; Remove-VM -Name test-sandbox -Force`
2. Run: `.\setup_env_windows.ps1 -VMName test-sandbox`
3. Verify provisioning completes (check `/var/log/provision.log` in VM)
4. Test SSH: `ssh -i $env:USERPROFILE\.ssh\id_ed25519_test-sandbox dev@test-sandbox.local`
5. Clean up: `Stop-VM -Name test-sandbox -Force; Remove-VM -Name test-sandbox -Force`

### Security Considerations

- `config.env` is chmod 600 / owner-only ACL and gitignored (stores git name/email only, never passwords)
- PostgreSQL uses scram-sha-256 for all TCP connections (peer auth for local socket)
- The script refuses to run as root inside the VM
- VNC password is required (min 8 chars), validated to block shell metacharacters, never stored
- VNC binds to all interfaces (`-localhost no`) to allow connections from the host — this is intentional and documented
- All user inputs are validated before use to prevent command injection
- External scripts (mise, ollama) are downloaded to temp files and validated before execution
- Host filesystem access is disabled inside the VM for isolation
- Windows: Ubuntu image downloads are verified against SHA256 checksums