Loopwright

Loopwright runs bounded repository work with independent verification and authenticated publication. A GitHub App control plane, reusable GitHub Action, and local CLI provide entry points.
Read the architecture overview and documentation for authority and qualification boundaries.
Architecture

- Admit: Validate intake and reserve a lease fence.
- Execute: Run an isolated Pi adapter under bounded authority.
- Verify: Bind independent evidence to the candidate.
- Publish & Remember: Reconcile publication and propose reviewed memory.
Highlights
- Non-delegable verification: Trusted gates issue authenticated receipts; model output cannot certify its own work. See evidence.
- Sandboxed execution: Native and container backends negotiate required isolation and fail closed when unavailable. See Sandbox Backends.
- Fenced state: Lease fences, clock guards, and retained reservations protect recovery. Unknown external outcomes require reconciliation. See state.
- Advisory decisions: Optional System-One routing uses confidence thresholds and deterministic fallbacks. See Decision Routing.
- Declarative taskpacks & suites: Define repository scope, triggers, compact step handoffs, conditional rules, baseline alignment (
baselineAlignment), and multi-domain TaskpackSuite manifests (.loopwright/suite.yaml) in YAML. See Declarative Taskpack and Taskpack.
- Run diagnostics (
RunEval): Export deterministic tool-repeat, ping-pong, repair-convergence, and per-role/per-step breakdowns via loopwright inspect and Run Health step summaries. See CLI.
- Hardware benchmark gates: Bind hardware
target.matrix cells to host-owned benchmark-gate.v1 slots and run outbound-only @loopwright/hardware-runner workers (loopwright runner relay|worker). See Task Contract and CLI.
- Reviewed memory: Content-addressed proposals apply separately after review. See memory.
- Capability closure: Inspect local evidence and external prerequisites with the closure matrix.
Features
The App, Action, and CLI share bounded contracts and evidence. The closure matrix records supported paths and external gaps.
Quick Start
Loopwright offers two operating modes sharing one verification kernel:
- Declarative Taskpack Mode (Simple Automation): Add
.loopwright/taskpack.yaml and run it locally with loopwright run --taskpack / loopwright step (omitting triggers, publication, and memory when unused) or wire uses: gpustack/loopwright@main in GitHub Actions; Loopwright compiles contracts, handler SHA-256 digests, and secret bindings automatically. Follow Declarative Taskpack and Taskpack.
- Managed Controller Mode (Fine-Grained Governance): Maintain an out-of-repo
TrustedRegistry (registry.yaml) and SHA-256-pinned ControllerConfig (controller.yaml) via the @gpustack/loopwright CLI. Follow Managed Controller.
Bootstrap or Migrate in One Prompt (llms.txt)
No custom skill is required. Open any coding agent inside your repository (for example, to migrate an existing automatic synchronized workflow) and paste this prompt (guided by Bootstrap Interview Reference):
Read https://docs.gpustack.ai/loopwright/llms.txt and its Bootstrap Interview Reference (https://docs.gpustack.ai/loopwright/references/bootstrap-interview.md). Inspect this repository first WITHOUT editing any files yet, then interview me one question at a time with repository-grounded defaults to agree on operating mode, which modules to automate or exclude, domain boundaries, update cadence, version/promotion holds, bounded host preflight -> offline sandbox -> independent verifier design, model pool (LOOPWRIGHT_PROVIDER_TOKEN), and workflow panel. Wait for my approval on the design summary before generating Loopwright config (apiVersion: loopwright.dev/v1alpha1) and running dry-run verification.
Install the Laptop CLI
To run Managed Controller cycles or repository audits locally (requires the runtime baseline; see Installation):
npm install -g --ignore-scripts @gpustack/loopwright
# or: pnpm add -g --ignore-scripts @gpustack/loopwright
loopwright run --taskpack .loopwright/taskpack.yaml --repo . --run-root ../runs --run-id demo
loopwright init --directory "$HOME/loopwright-config"
loopwright check --config CONFIG --registry REGISTRY --registry-sha256 DIGEST
For workspace development and repository closure verification:
git clone https://github.com/gpustack/loopwright.git
cd loopwright
npm ci && npm run build
node packages/cli/dist/main.js closure --verify-failures
Replace draft placeholders with approved configuration before running check (or use the Managed Controller prompt). Static checks do not establish execution readiness. See CLI.
Usage
Automated Upstream Sync

Save this complete manifest as .loopwright/taskpack.yaml:
apiVersion: loopwright.dev/v1alpha1
kind: Taskpack
metadata:
name: docs-sync
spec:
goal:
candidate: Refresh documentation from upstream sources and pass every local check.
noChange: Confirm the documentation needs no change and settle as no change.
scope:
writable:
- docs/**
protected:
- policy/protected-notes.md
upstreams:
- id: engine
kind: github-release
source: octocat/engine
watchedPaths:
- docs
proposal:
path: docs/proposal.json
requiredFields:
- schema_version
- candidates
schemaVersion: 1
verification:
localChecks:
- id: docs-proposal-json
implementation: json-artifact.v1
externalGates: []
publication:
mode: pull_request
targetBranch: main
headBranchPrefix: loopwright-docs-
titleTemplate: 'docs: sync upstream documentation'
memory:
directory: .loopwright/memory/docs-sync
apply: separate-pull-request
onNoModelBudget: deterministic-observations-only
triggers:
schedule: true
workflowDispatch: true
releasePublished: false
commentCommands:
- retry
- revise
- status
sandbox:
preferredBackends:
- macos-seatbelt
- linux-bwrap
- linux-landlock
- docker
networkMode: none
requiredCapabilities:
- filesystemReadContainment
- filesystemWriteContainment
- protectedPathReadOnlyMask
- networkIsolation
- processTreeCleanup
deniedReadPaths:
- ~/.ssh
- Scope: Keep writable and protected paths separate; place memory outside writable scope.
- Host: Supply trusted bindings and qualified gate and publication services separately.
- Triggers: An upstream declaration does not itself install a scheduler or webhook.
See Declarative Taskpack.
Slash-Command Maintenance

A GitHub App supplies a scoped installation token to the consumer workflow. Register the App and store its credentials as described in GitHub App.
A consumer repository can declare this workflow to receive /loopwright retry and /loopwright status events:
name: loopwright
on:
schedule:
- cron: '0 3 * * *'
workflow_dispatch: {}
issue_comment:
types: [created]
permissions:
contents: read
jobs:
taskpack:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/create-github-app-token@v1
id: app-token
with:
app-id: ${{ secrets.LOOPWRIGHT_APP_ID }}
private-key: ${{ secrets.LOOPWRIGHT_APP_PRIVATE_KEY }}
- uses: gpustack/loopwright@main # Pin a reviewed immutable revision.
id: loopwright
with:
taskpack-path: .loopwright/taskpack.yaml
event-name: ${{ github.event_name }}
event-path: ${{ github.event_path }}
dry-run: 'true'
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
LOOPWRIGHT_PROVIDER_TOKEN: ${{ secrets.LOOPWRIGHT_PROVIDER_TOKEN }}
LOOPWRIGHT_GATE_SIGNING_SECRET: ${{ secrets.LOOPWRIGHT_GATE_SIGNING_SECRET }}
LOOPWRIGHT_PUBLICATION_SIGNING_SECRET: ${{ secrets.LOOPWRIGHT_PUBLICATION_SIGNING_SECRET }}
- Authorization: Configure comment commands in the taskpack and authorize the actor.
- Credentials:
compileDeclarativeTaskpack binds ${LOOPWRIGHT_PROVIDER_TOKEN}, ${LOOPWRIGHT_GATE_SIGNING_SECRET}, and ${LOOPWRIGHT_PUBLICATION_SIGNING_SECRET} as unexpanded templates on disk and resolves them in memory during controller execution.
- Dry-run:
dry-run: 'true' compiles and validates artifacts outside the checkout; live execution requires a wired host controller delegate.
| Variable |
Consumer |
Purpose |
GH_TOKEN |
GitHub API |
Short-lived installation token from actions/create-github-app-token@v1 |
LOOPWRIGHT_PROVIDER_TOKEN |
provider |
Authenticates the isolated Pi authoring role against the model provider |
LOOPWRIGHT_GATE_SIGNING_SECRET |
gate |
Signs external gate.v1 requests and verifies HMAC verdict receipts |
LOOPWRIGHT_PUBLICATION_SIGNING_SECRET |
publisher |
Signs PR publication dispatches and verifies publication receipts |
See Action secrets and environment and GitHub App.
Native OS Sandboxes

Configure spec.sandbox inside .loopwright/taskpack.yaml:
apiVersion: loopwright.dev/v1alpha1
kind: Taskpack
metadata:
name: docs-sync
spec:
# Other Taskpack sections omitted; see the taskpack above.
sandbox: # Optional host isolation policy
preferredBackends: # Optional priority order
- macos-seatbelt
- linux-bwrap
- linux-landlock
- docker
networkMode: none
requiredCapabilities:
- filesystemReadContainment
- filesystemWriteContainment
- protectedPathReadOnlyMask
- networkIsolation
- processTreeCleanup
deniedReadPaths:
- ~/.ssh
- Negotiation: Missing required capabilities fail closed.
- Host: Backend availability and isolation require host qualification.
| Backend |
Host or boundary |
macos-seatbelt |
macOS Seatbelt |
linux-bwrap |
Linux bubblewrap |
linux-landlock |
Linux Landlock |
docker |
Docker container |
direct-dedicated |
Dedicated host; declared capabilities still apply |
See Sandbox Backends.
System-One Decision Routing

An integrating host can load this decisions.yaml policy:
apiVersion: loopwright.dev/v1alpha1
kind: DecisionPolicy
spec:
enabled: true # Explicit opt-in.
disclosurePolicy: public-metadata-only # Reject raw repository content.
provider: typesafe-jev
minConfidence: 0.8
confirmThreshold: 0.6
hardDeadlineMs: 5000
maxAttempts: 1
Alternatively, declare spec.decisions inside .loopwright/taskpack.yaml: both the GitHub Action and CLI wire live @loopwright/decisions adapters into ControllerPorts.decisions (falling back deterministically when credentials or endpoints are unavailable).
apiVersion: loopwright.dev/v1alpha1
kind: Taskpack
metadata:
name: docs-sync
spec:
# Other Taskpack sections omitted; see the taskpack above.
decisions: # Optional System-One triage policy
enabled: true
provider: typesafe-jev # Optional
disclosurePolicy: public-metadata-only
minConfidence: 0.8
confirmThreshold: 0.6
hardDeadlineMs: 5000
maxAttempts: 1
- Authority: Decisions are advisory and cannot approve gates.
- Disclosure: Only approved, sanitized inputs may leave the host.
- Fallback: Low confidence or unavailable providers use deterministic fallback.
| Provider |
Dialect |
typesafe-jev |
System One |
openai-decisions |
OpenAI Decisions |
startlux-decision |
System One |
microsoft-decision |
System One |
perplexity-decider |
System One |
cloudflare-clef |
System One |
liquid-d1 |
System One |
Provider profiles are implemented interfaces; fixture tests do not establish live provider qualification. See Decision Routing.
Recovery, Reconciliation, and Closure

Inspect the run and reconcile an authenticated receipt when required:
loopwright status --run-root TRUSTED_ROOT --run-id RUN_ID
loopwright inspect --run-root TRUSTED_ROOT --run-id RUN_ID --output INSPECTION_DIR
loopwright reconcile --config CONFIG --registry REGISTRY --registry-sha256 DIGEST \
--repo REPO --run-root TRUSTED_ROOT --run-id RUN_ID --receipt RECEIPT
loopwright closure --verify-failures
- Unknown: Preserve uncertain external effects until authenticated reconciliation.
- Paths: Keep trusted config, registry, and run root outside the untrusted checkout.
| Exit |
Execution meaning |
| 0 |
Successful static command or completed run |
| 2 |
Usage or configuration rejected |
| 3 |
Unsupported capability or blocked work |
| 4 |
Failed acceptance or execution |
| 5 |
Allowance exhausted |
| 6 |
Deadline expired |
| 7 |
Reconciliation or ownership needed |
| 8 |
Authoritative result unavailable or incident |
| 130 / 143 |
Accounted signal, subject to uncertainty precedence |
Closure has command-specific exit semantics. See CLI.
License
Copyright (c) 2026 The Loopwright Authors. Licensed under the Apache License 2.0.