> ## Documentation Index
> Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> From your invite to your first issue built into a pull request by a Claude Code session on your machine.
By the end of this page, one of your GitHub issues is built into a pull request by a Claude Code session on your machine. The dashboard shows the pull request, the session that wrote it, and the checks it passed.
## Before you start
* **Claude Code** on your machine. OuterLayer records Claude Code sessions.
* **Node.js 22 or later**, to run the OuterLayer CLI. Your repository does not need to use Node.
* **A GitHub repository with at least one open issue.** You need to be allowed to install a GitHub App on it; [Connect a repository](/connect-repository#where-to-start-it) says who can. The examples use issue 42.
* **Acceptance criteria in that issue, if you have them.** `/build` records the issue's criteria, or drafts them when it has none. See [`outerlayer emit criteria`](/reference/cli-emit#outerlayer-emit-criteria).
You do not need a host. A host is a machine where a runner builds issues unattended, and you can add one after your first build.
## Create your factory
OuterLayer is invite-only for now. You'll get an email invite from the OuterLayer team. If you don't have one, join the waitlist from the [login page](https://app.outerlayer.ai/auth/login).
Because you were invited, your organization and a factory named Default already exist, so there is nothing to create. [Key concepts](/concepts#where-work-lives) says what a factory is.
1. Open the link in the invite email. It signs you in and opens a page where you set a password.
2. Instead of a password, choose **Continue with GitHub** or **Continue with Google**. Either one links to the account you were invited to.
3. You land on the Default factory's Work page.
Your factory's Work page opens on a setup panel, **Build your first issue**, with the same four steps as this page. Its **Read the quickstart** link opens this page.
Where pull requests open, and where checks are read from. The panel shows this step's two parts up front:
1. **Install the OuterLayer GitHub App.** Choose **Connect GitHub repository**. Grant only the repositories this factory should see. On a GitHub organization, only an owner can install it; other members can request it from an owner.
2. **Link the repository.** Back here, pick the repository and the branch your pull requests target. Policy and checks are read from that branch. Choose **Link repository** to pick them.
The step then shows **Repository linked**, with the repository and branch.
The App reads issues, pull requests and CI results. It posts comments and checks on GitHub only when you turn them on in the factory's settings. A runner build also uses the App to push its branch and open its pull request.
Needs Node 22. Run these in your repository's checkout. Approve the sign-in link when it opens.
```bash theme={"system"}
npm install -g @outerlayer/cli
outerlayer login
outerlayer init --factory /
```
This page installs the CLI once, with `npm install -g @outerlayer/cli`, and then runs it as `outerlayer`. `/build` and the other skills run that command, so install it once per machine. A host needs the same install. The `outerlayer` MCP server that `init` adds for Claude Code runs `npx -y @outerlayer/cli mcp serve`, so it works without the install.
The panel fills in `/` for you. It is your organization's and factory's names from the dashboard's address.
`login` signs this machine in to your account. It prints a link and opens it in your browser; approve it there. You do this once per machine.
`init` sets up the repository. On a terminal it asks one question, whether plain `claude` should start through `outerlayer claude`, and writes nothing to your shell until you say yes. It:
* connects the repository to your factory
* installs the hooks that record your Claude Code sessions
* adds the starter skills, including `/build`, and two MCP servers for Claude Code
* runs `doctor`, a health check that may warn on a fresh machine ([which warnings](/reference/cli-capture#outerlayer-doctor))
It changes nothing you wrote by hand. The files it adds stay uncommitted until step 3.
Choose **Copy a prompt for your agent instead**, open Claude Code in your checkout, and paste it. Claude runs the same commands and hands you each link to approve. This is the prompt:
```text theme={"system"}
Set up OuterLayer in this repository.
OuterLayer is an open-source software factory: an issue goes in, and a reviewed
and verified pull request comes out, built by the coding agents this team already
runs, in this repository. Setup signs this machine in to my OuterLayer account,
connects this repository to my team's factory, and installs the hooks and skills
that let you build issues for it.
1. Run `npm install -g @outerlayer/cli`, so the `outerlayer` command is on the PATH.
The skills that setup installs run that command.
2. Run `outerlayer login`. It prints a link and a code. When it does, give it to me and
wait; I approve it in my browser. Then run its check as
`outerlayer login --check `, with the id it printed, until it
stops exiting 75.
3. Then run `outerlayer init --factory /`. It connects the repository, installs the
hooks and skills, and runs a health check. If it prints a link to link the
repository, give it to me, wait for me to say done, then run
`outerlayer connect --factory /`.
4. When `init` ends, tell me what it says to do next, including any line about
committing and pushing `.outerlayer/`, and what `doctor` reported. Then stop.
I add work from the Work page, not from here.
Never print anything these commands call a token or a key.
```
`init` connects the repository by running `connect`. With `--factory`, it uses the factory you name; without it, `connect` picks a factory by itself when only one fits. If the repository is not linked to the factory yet, `connect` prints the link to the factory's Work page and exits 2. Finish step 1 there, then run `connect` again: `outerlayer connect --factory /`.
`login` works on a machine with only a terminal: open its link on any other device. For a machine where nobody can approve a link, such as CI, choose **No browser on that machine?** under the commands. It makes a factory key, shown once, and shows commands with the key filled in to paste. Those commands run `init --local`, which installs the session hooks only. They do not connect the repository or add the starter skills.
The step shows **OuterLayer installed** once step 3 is done.
Every flag and exit code is in [Capture commands](/reference/cli-capture) and [Cloud commands](/reference/cli-cloud#outerlayer-connect).
Merge the files `init` wrote into your base branch. Checks run only once they're there. The panel names your base branch and shows these commands:
```bash theme={"system"}
git add AGENTS.md .agents .claude/skills .mcp.json .outerlayer
git commit -m "Add OuterLayer setup"
git push
```
`git push` pushes the branch you are on. If that is not your base branch, open a pull request from it and merge it.
`init` lists every path it wrote ([which files](/reference/cli-capture#outerlayer-init)):
* `AGENTS.md`: your agent instructions.
* `.agents/skills/`: the skills.
* `.claude/skills`: a link to `.agents/skills` for Claude Code.
* `.outerlayer/`: your policy and config, and two checks in `.outerlayer/validators/` (`code-review.yaml` for the code review and `acceptance-criteria.yaml` for the criteria judge).
* `.mcp.json`: the two MCP servers.
The session hooks are not among them. `init` writes the hooks to `~/.claude/settings.json`, your own Claude Code settings, outside the repository. Each teammate runs `init` on their own machine to get them.
Do this before you build anything. This step ticks itself once OuterLayer sees the files on your base branch. OuterLayer reads the branch each time it is pushed to, so the tick shows shortly after the merge, in every browser and for every teammate.
Pick an issue, choose Build locally, then run the line under Run it yourself.
1. On the panel, choose **Add your first issue**. A dialog lists the repository's open issues. Choose **Build locally** beside your issue.
The issue is now a **work item** with **a number of its own**: issue 42 might become item 7. OuterLayer's pages and commands use the item number, never the issue number. The item's page opens, with that number in its heading.
2. In your checkout, switch to the base branch and pull, so the setup from step 3 is there.
3. On the item's page, open the **Activity** tab and expand **Run it yourself**. Copy the line it shows. For item 7 it is:
```bash theme={"system"}
OUTERLAYER_WORK=7 claude "/build"
```
4. Run it in your checkout. It starts Claude Code linked to item 7. `/build` reads the issue, writes the change, runs your repository's checks, and opens the pull request.
`/build` reads the issue's criteria in any form you write them, such as a heading with a list, a checklist or a "done when" sentence, and records them as written. When the issue has none, the build drafts criteria from the issue's description and records them. The item's Criteria tab says they were drafted. You can replace them with your own list with [`outerlayer emit criteria`](/reference/cli-emit#outerlayer-emit-criteria). To write the criteria yourself first, add a criteria section to the issue, or write the issue with `/spec`, which `init` installs.
**Build**, beside **Build locally** in the dialog, queues the item for a runner instead. Use it once you have one: see [Set up your first host](/set-up-a-host).
The item's **Sessions** list shows your session as it runs. Answer Claude's permission prompts as they come.
You are done when the item's page shows the pull request and its evidence rows, one row per check, on its **Checks** tab. Open the session to read every turn, the tools it called and what it cost. [Work on an item locally](/launch-a-session) explains how a session is linked to an item.
## What gets uploaded
Only sessions linked to a work item upload, and known credential formats are removed on your machine first. See [Work on an item locally](/launch-a-session) for the rule and [What leaves your machine](/what-leaves-your-machine) for everything that is sent.
## From now on
Add each issue the same way, and review its pull request on the item's page: approve it or send it back. See [Review and merge](/review-the-work).
To have issues built without you, [set up a host](/set-up-a-host) later, then choose **Build** in the add dialog. If no runner takes an item, see [Troubleshoot builds](/troubleshoot-builds).
To take an item off the Work page: `outerlayer work remove --item 7 --reason "opened by mistake"`.
To add another repository, see [Connect a repository](/connect-repository).
Rename the organization under **Organization settings → General**, from the account menu at the bottom left. Rename the factory under its **Settings → General**, in the **Name** section. The gear on its card in the Factories list opens that page.
## Next steps
A machine you control that builds items unattended.
Everything that uploads, and the two tiers that upload less.
Add a tracker so its issues appear in the same dialog.
Add teammates, each signed in on their own machine.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.