Skip to content

CLAUDE.md

Latest commit

 

History

History
59 lines (40 loc) · 1.73 KB

CLAUDE.md

File metadata and controls

59 lines (40 loc) · 1.73 KB

Claude Code Guide

Instructions for AI assistants working with this codebase.

Project Overview

Testman is an ephemeral container system for running AI coding assistants safely. Containers are disposable (--rm), with persistence via mounted volumes.

Agentman is the flagship sandbox—pre-configured for Claude Code, Gemini CLI, Aider, and other AI tools.

Critical Constraints

  • ARM64 only: All builds use --platform linux/arm64
  • Podman only: Never suggest Docker
  • Ephemeral only: No start/stop/resume—fresh containers every run
  • No hardcoded secrets: Personal data comes from environment variables

Directory Structure

sandboxes/
├── base/           # Foundation image (Containerfile, build.zsh, run.zsh)
├── agentman/       # AI coding assistants sandbox
├── TEMPLATE/       # Template for new sandboxes
├── lib/            # Shared functions (common.zsh)
└── scripts/        # Utility scripts

Common Tasks

"Create sandbox for tool X"

cp -r sandboxes/TEMPLATE sandboxes/toolname
# Edit run.zsh, replace {TOOL_NAME}, {TOOL_COMMAND}, {INSTALL_COMMAND}, {PACKAGE_NAME}

"Add package to base image"

Edit sandboxes/base/Containerfile, add to appropriate layer, rebuild with ./build.zsh --public.

"Enable auditing"

Add --audit flag: ./run.zsh --workspace ~/project --public --audit

"Debug container issues"

Check ~/.testman/containers/<project>/logs/ for syscall and filesystem logs.

Anti-Patterns

  • ❌ Docker commands (use Podman)
  • ❌ Multi-architecture builds (ARM64 only)
  • ❌ Container resume/restart logic (ephemeral only)
  • ❌ Hardcoded personal info (use env vars)
  • ❌ Per-tool Containerfiles (use runtime installation)