Padreug
df0fd9a9ba
The forgejo-sandbox / reforge harness, lifted out of the machine config into a host-agnostic, generic engine anyone can consume with Nix. Two layers: - engine (this repo) — nixosModules.reforge stands up the sandbox forge, provisions role accounts + tokens, enforces branch protection, and puts the reforge-* CLI + forgejo-mcp on PATH. Carries no project specifics. - run config — per-project manifest/charter/agenda/issues an adopter fills in; scaffold one with the `reforge` flake template. Portability fixes vs the in-config version: - forgejo-mcp resolved from $REFORGE_MCP_BIN or PATH, never a named host (kills the nixosConfigurations.omni hardcode). - all instance data + paths parameterized via REFORGE_* env, baked into the reforge-scripts wrappers from module options (configDir, agentsDir, refsDir, org, port, tokenOwner, ...). - option namespace neutral (reforge.* not omni.packs.*); settings policies carry no absolute /etc/nixos paths. - role briefs + orchestrator playbook genericized: all project specifics point at the charter; refs corpus optional. Validated: nix flake check (eval) + builds of forgejo-mcp, reforge-scripts, and a module-eval check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 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`](docs/reforge.md)
|
|
- **How the sandbox is built:** [`docs/architecture.md`](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)
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
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. See `docs/reforge.md` for the follow-up ideas (markdown export
|
|
of a run's issues at close; Forgejo Actions as a CI gate ahead of review).
|
|
|
|
## License
|
|
|
|
MIT — see [`LICENSE`](LICENSE).
|