claude-forgejo-sandbox

A local Forgejo sandbox that runs a role-isolated agent team as a simulated software dev team — rebuilding a software stack from pinned clean bases toward a declared target, coordinating entirely through the forge (issues, branches, PRs, enforced independent review). We call one such rebuild a reforge.

The point is review isolation: each role is a separate agent session with its own scoped forge token, and the security reviewer pulls the PR diff itself instead of being handed the implementer's rationale. main is protected everywhere — only the security-lead's approval unlocks a merge, and not even the admin can push through branch protection.

• What a reforge is and how to run one: docs/reforge.md
• How the sandbox is built: docs/architecture.md

Two layers

• The engine (this flake) — host-agnostic and generic: a NixOS module (nixosModules.reforge) that stands up the forge, provisions role accounts + tokens, enforces branch protection, and puts the reforge-* CLI + forgejo-mcp on PATH. It carries no project specifics.
• A run config — the per-project data you fill in: manifest.txt (repo set + pinned bases + targets), charter.md (the standard changes are judged against), agenda.md + issues.tsv (this run's worklist). Scaffold one with the reforge flake template.

Quickstart (NixOS)

# 1. Scaffold a run config
nix flake init -t git+https://git.atitlan.io/aiolabs/claude-forgejo-sandbox#reforge
#    edit manifest.txt / charter.md / agenda.md / issues.tsv, and flake.nix
#    (set tokenOwner)

# 2. Add the run's module to your NixOS host and rebuild
#    imports = [ inputs.myreforge.nixosModules.default ];
sudo nixos-rebuild switch

# 3. Drive a run
reforge-smoke        # verify the toolchain + gates
reforge-seed         # create repos from the manifest, seed the charter
reforge-kickoff      # file the agenda as issues
reforge-role security-lead     # one terminal per role …
reforge-orchestrator           # … or let one agent drive the whole run
reforge-harvest run-1          # export the run's record (issues, reviews,
                               # charter tree) as markdown + JSON for triage

Not on NixOS? The forge is services.forgejo, so declarative provisioning is NixOS-native. You can bring your own Forgejo (a container) and run the scripts/*.sh directly with the REFORGE_* environment variables set — you just lose the turnkey provisioning. This is NixOS-first, not cross-platform.

Configuration

All knobs are reforge.* NixOS options (see modules/reforge.nix): enable, httpPort, org, repoName, roles, requiredApprovers, adminUser, tokenOwner, configDir, agentsDir, refsDir, forgejoMcpPackage. Every script default is also overridable at runtime via the matching REFORGE_* variable.

Flake outputs

Output	What
nixosModules.reforge (= .default)	The sandbox forge + provisioning + CLI
packages.<sys>.forgejo-mcp	The MCP server binary
packages.<sys>.reforge-scripts	The reforge-* CLI (standalone, template defaults)
apps.<sys>.reforge-*	nix run .#reforge-seed, etc.
templates.reforge (= .default)	Run-config scaffold

Status

Extracted from the aiolabs machine config where it was first built and run. The engine is generic; the aiolabs runs (their real charter/agenda/manifest) stay private. Remaining follow-up: Forgejo Actions as a CI gate ahead of review (see docs/architecture.md).

License

MIT — see LICENSE.