Skip to content

CLAUDE.md

Latest commit

 

History

History
54 lines (35 loc) · 2.35 KB

CLAUDE.md

File metadata and controls

54 lines (35 loc) · 2.35 KB
Raw

foundry-sandbox

Docker-based sandbox environment for running Claude Code with isolated credentials.

Development

  • foundry_sandbox/ - Python CLI package (cast entry point via pyproject.toml)
  • unified-proxy/ - Credential isolation proxy (mitmproxy addons, git API)
  • stubs/ - Stub files injected into sandboxes (CLAUDE.md, etc.)
  • tests/ - Test scripts including security red-team tests

Pre-commit

Always run ./scripts/ci-local.sh before committing to catch CI failures locally. Use --all to include integration tests, --no-fail-fast to see all results.

Testing

./scripts/ci-local.sh        # Local CI validation (run before commit)
./tests/redteam-sandbox.sh   # Security validation (run inside sandbox)

Run ./scripts/ci-local.sh before pushing to catch CI failures early.

Documentation

  • docs/README.md - Documentation index
  • docs/architecture.md - System architecture
  • docs/configuration.md - Configuration options
  • docs/getting-started.md - Setup guide
  • docs/usage/ - Commands and workflows
  • docs/security/ - Security model and threat analysis

Important: Read docs/security/security-model.md to understand the threat model and security boundaries before making changes to sandbox isolation.

Important: Read docs in docs/adr for decision records on architecture.

Git Mode

cast git-mode <sandbox-name> --mode <host|sandbox> toggles a sandbox's git config between host-friendly and proxy-compatible layouts:

  • --mode host — sets core.worktree to the real host path so IDE and shell tools work normally
  • --mode sandbox — sets core.worktree to /git-workspace (container path) for proxy-routed git operations

The command validates paths, updates .git/config.worktree, and syncs the running proxy container immediately. The sandbox name is auto-detected if you run it from inside a worktree.

Releasing

  1. Bump the version in pyproject.toml
  2. Add a new section to CHANGELOG.md with the version and date
  3. Commit, push to main
  4. Create a git tag: git tag v<version> && git push origin v<version>

The .github/workflows/release.yml workflow triggers on v* tags and handles both the GitHub release and PyPI publish automatically. Do not create the GitHub release manually with gh release create — the workflow does this and will fail if the release already exists.