Docs
Everything you need to run ForgeOS, and nothing you do not.
ForgeOS is operated by describing outcomes. There is no configuration language to learn, so this is short on purpose.
Quickstart
From nothing to a reviewed change
Five steps, one repository, no model provider required — the free deterministic source covers the first run.
1 · Sign in
Create your account with Google or GitHub at signup. Signing in creates your workspace; there is no separate registration.
2 · Connect a repository — or try the sample
Sign in with GitHub and pick the repository — one consent screen covers identity and repository read; your repository is never written to by connecting. Not ready to point ForgeOS at your own code? One click on Today creates a small sample repository, and every step below works identically against it.
3 · Ask for something
Type the outcome into the box on Today. ForgeOS reads your source and writes a plan derived from it — steps, scope claim, and what it will not do. Nothing runs yet.
4 · Approve the plan
The builder takes an isolated copy, asks the cheapest source that can do the work, runs your repository’s own tests, and submits the exact diff with its evidence. Nothing unverified is ever submitted.
5 · Review and accept
The diff is on the goal page. Accepting writes it onto a forgeos/… branch in the connected checkout — once you allow writing. Never pushed, never your branches; merge it when you choose.
What you never do
Paste API keys to get started, choose a model, configure a runner, or watch a terminal. Connect OpenRouter later — one click, billed to your own account — and bigger goals route to real models through the same flow.
Every button above calls the same /api/mc/* endpoints you can call yourself; docs/QUICKSTART.md in the repository walks the identical journey with curl.
Getting started
Writing a goal
A goal is one sentence describing an outcome. ForgeOS decides how; you decide what and whether.
Describe the outcome
“Make the checkout page load in under a second on mobile.” Not “add a cache to the product query.” The second one is a solution, and it may be the wrong one.
Choose the repository
Only repositories connected to your instance appear. Connecting one grants read access and nothing else.
Narrow the scope, or do not
You can limit a goal to specific paths. Leaving it open lets ForgeOS claim the whole repository, and it tells you what it intends to touch either way.
Planning changes nothing
Submitting a goal records it and produces a plan. No branch is written and no code changes until work starts.
Two goals cannot hold overlapping paths in the same repository at the same time. If you start a second goal that overlaps a running one, it waits rather than racing it.
Reference
What the states mean
These are the states ForgeOS actually uses internally — not a simplified view layered over them.
| State | What it means | What moves it on |
|---|---|---|
| planned | Recorded. Nothing has been changed. | ForgeOS queues it once the plan is settled. |
| ready | Queued to start. | An agent picks it up. |
| leased | Being worked on now, on a branch, in scoped paths. | The agent submits the work, or fails, or stops responding. |
| blocked | Stopped because ForgeOS needs a decision or an input it does not have. | You. There is no automatic route out. |
| in review | Built and submitted. Waiting for a person to accept or reject it. | Your approval, or your rejection, which sends it back to be redone. |
| completed | Accepted. This is the only terminal state that counts as done. | Nothing — it is final. |
| failed | It did not work and ForgeOS stopped instead of retrying quietly. | A new goal, or a retry you start. |
| cancelled | Stopped by you, or superseded. | Nothing — it is final. |
Mission Control
The goal workspace
Open any goal from Work. Seven views, each answering one question.
| View | Answers |
|---|---|
| Conversation | What you have said about this goal, and what ForgeOS said back. This is the primary way to steer work. |
| Plan | What ForgeOS intends to do, and below it, the recorded history of what has actually happened. |
| Changes | Which files the work touched, on which branch. |
| Checks | Which tests and scans ran, and what they found. |
| Preview | A running copy of the change before it reaches production, plus the raw recorded log entries. |
| Proof | What has been verified, what has not, and what this instance is not able to verify at all. |
| Release | Deployment state, whether rollback is available, cost so far, and anything blocking release. |
Anywhere a view has nothing to show, it says which of two things is true: nothing has happened yet, or nothing is connected that could produce it. Those are different, and the difference is never hidden.
Working with ForgeOS
Decisions
ForgeOS interrupts you for two reasons only. Both appear under Needs you at the top of Mission Control, at every screen size.
Work is finished and needs accepting
Approve and the goal is complete. Decline and the work goes back to be done again — declining does not delete it. Nothing is deployed by either choice.
ForgeOS stopped and needs you
It could not continue and recorded why. You can stop the goal, or open it and say what it needs in the conversation.
Every decision card states what happens if you do nothing. In both cases the answer is that nothing happens: ForgeOS does not proceed on its own after a timeout.
Verification
Proof, and what has to be connected for it
Proof is the part of ForgeOS that is easiest to fake and most important not to. Read this before you trust a green mark anywhere in the product.
Checks come from runners
Tests, security scans, accessibility checks, runtime probes and deployment state are produced by runners connected to your instance. Nothing is inferred.
Not run is not passed
A check with no runner behind it is shown as “Not run”. It is never rendered as a pass, and never omitted so the list looks complete.
An agent's report is a claim
When an agent submits finished work, its description of what it did is labelled as its own report, not as verification.
Check your instance. The status page lists which capabilities are connected. If runners are listed as not connected, no goal on that instance can produce a verified check, and the product will tell you so on every goal.
Something here not clear?
Documentation that does not answer your question is a defect. Tell us which part.