ForgeLoopStart with the boundaries
Connect a repository. Bring your runner.
The website is the control plane. The runner is where repository work happens. Keep those two roles clear during setup.
Before you begin
You need a GitHub account with access to the deployment, a repository you can authorize, and a computer that can run Git and Docker. The browser coordinates delivery; your enrolled runner performs the repository work.
- The downloads page shows the assets present in the latest complete release. The supported desktop targets are Windows x64/ARM64, macOS Apple Silicon/Intel, and Linux x64/arm64. Linux formats include DEB, RPM, portable tar.gz, and Arch pacman packages.
- Install Git and Docker, and start Docker for first-time pairing. Check requirements only inspects readiness.
- Have a supported model provider API key ready. Provider usage is billed by that provider; installing the runner does not add API credit.
Connect GitHub and select a repository
Sign in with GitHub, open Repositories, and install the ForgeLoop GitHub App for the repositories you want to use. Signing in identifies you; installing the App grants repository access. Complete both steps and confirm the repository appears in the console.
- Choose the intended base branch and repository harness. Keep your existing language, framework, and Git history.
- Set the intake label and, if you want work to wait for assignment, enable the gate. Leave the login blank to accept anyone GitHub assigns or enter one exact login. An issue must satisfy the configured intake rules.
- If a repository is missing, check the App installation’s selected repositories and your organization access.
Install and pair your runner
Download the package for your operating system, install it, and open ForgeLoop Runner. In Connect, use Connect in browser. Compare the fingerprint in the desktop app with the browser approval page, then approve using an organization administrator account.
- Return to the desktop app to finish connecting. The browser approval alone does not start work.
- Use Check saved connection to verify enrollment. Reopening a configured app takes you to Run.
- The current installers are unsigned previews. The download page includes version information, platform details, and optional SHA-256 verification.
Configure your provider and estimated prices
In Provider, choose your provider and model, enter its API key, and save. Credentials are stored on the runner using the operating system’s credential protection. A blank key field after reopening keeps the saved credential; it does not mean the key was lost.
- Check saved key locally verifies storage without making a model request. It does not confirm provider credit or model access.
- Public base token prices are looked up automatically. You can override account-specific rates; unknown pricing appears as N/A, and estimated spending is not a provider invoice.
- Start runner can open an installed local Docker engine on Windows, macOS, or Linux and wait up to two minutes for readiness. Cancel Docker startup leaves the runner stopped.
- Starting Docker makes no model request. Once the runner starts, eligible work can incur provider charges.
Define what a passing change means
Before starting work, review the repository’s verification commands and Harness & policy settings. A harness tells ForgeLoop how to work with and check a repository. Choose commands that can prove the behavior you care about, including failure paths.
- Set task and budget limits appropriate to the change. Include test, build, and other required gates for your repository.
- Decide whether delivery needs human approval. Enable auto-merge only when you want eligible changes merged after its checks pass.
- Keep the runner stopped while preparing an issue if you are not ready to incur provider charges.
Submit a small first issue
Start with one change you can review. Describe the current behavior, the expected behavior, the files or feature area involved, and observable acceptance criteria. Apply the configured label and assignee when you are ready for intake.
- Example: “Show an empty state when search returns no results. Keep the search input and filters visible. Add a test for zero results and preserve existing loading and error states.”
- Avoid open-ended requests such as “improve the whole app.” State what is outside the requested change.
- Follow the run in Runs. Open its details to inspect tasks, events, verification output, and delivery progress.
Review, pause, and update
Review the proposed diff alongside its acceptance coverage and verification evidence. A completed run does not replace your deployment process. After delivery, use your normal release checks for the target application.
- Pause after current work lets active work finish before the runner claims more. It does not reverse charges already incurred.
- To update: pause, wait for work to finish, close the app, install the newer package, and reopen. Saved identity and provider settings live outside the installation directory.
- Use Usage & costs to inspect estimated spending and pricing coverage. Archive finished runs to tidy the queue; archived runs remain included in usage totals.
When a run does not start
Open Getting started in the console to check repository setup and diagnose intake. Work can be waiting for authorization, an intake rule, an available runner, or a policy decision. Check the relevant stage before resubmitting the same issue.
- Repository missing: review GitHub App access and your organization membership.
- Issue waiting: check the exact label and required assignee, then inspect intake diagnostics.
- Runner offline: reopen the app, check the saved connection, and confirm Git and Docker readiness.
- Provider failure: check the chosen model, API access, and provider billing. A local key-storage check cannot verify those.
Ready for your first run?
Connect a repository, set up your runner, and start with a small change you can review.