> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> From signup to your first issue built into a pull request, from the Work page, in about ten minutes.
By the end of this page, one of your issues is a work item on your factory's Work page. A host builds it into a pull request, and the item's page shows the pull request and its checks.
A new factory's Work page opens on a three-step setup panel. Steps 1 to 3 below match it. Step 4 happens on the item's page.
## Before you start
* **Claude Code**, installed and on your `PATH`. Only Claude Code has a session-start hook, so only its sessions are recorded as work.
* **Node.js 22 or later.**
* **A GitHub repository with at least one open issue**, where you may install a GitHub App. [Connect a repository](/connect-repository#where-to-start-it) says who can install it. The examples use issue 42.
* **A host, or time to build it yourself.** A host is a machine running `outerlayer runner` for your factory. Without one, the item waits, and you build it in a session of your own. To set one up, see [Run work on your machines](/run-work-on-your-machines).
The CLI runs as `npx @outerlayer/cli`. Other pages write `outerlayer` for short. If you installed it with `npm install -g @outerlayer/cli`, type `outerlayer`.
## Create your factory
Sign up at [app.outerlayer.ai](https://app.outerlayer.ai). Create an organization, then a factory. [Key concepts](/concepts#where-work-lives) says what a factory is.
If someone at OuterLayer invited you, skip that. Your organization and a factory named Default already exist, and the invite link opens the Default factory's Work page. Rename the organization under **Organization settings → General**, from the account menu at the bottom left. Rename the factory from the **Factory settings** menu, the gear on its card in the Factories list, by choosing **Rename**.
The factory's Work page opens on the setup panel. Step 1 unlocks steps 2 and 3. Each step is done without leaving the page.
Choose **Connect GitHub repository** on the panel. GitHub asks whether to grant all repositories or only selected ones. Select the one holding your issue.
GitHub returns you to the panel. Choose **Link repository**, then pick the repository and its base branch. Checks and policy are read from that branch. The step marks itself done.
The App reads issues, pull requests and CI results. It posts nothing on your pull requests unless you turn that on in the factory's settings. That setting is off by default.
Run two commands yourself, or paste a prompt into your coding agent. Neither asks for a key. This step never marks itself done.
**Run the commands.** Run this block inside your repository's checkout:
```bash theme={"system"}
npx @outerlayer/cli login
npx @outerlayer/cli init --factory /
```
`login` signs you in once per machine. You approve a link in your browser. Replace `/` with your organization's and factory's names, as they appear in the dashboard's address. The setup panel fills them in for you.
`init` does four things, and asks nothing:
* connects the repository to your factory
* installs the capture hooks
* adds the starter skills and the OuterLayer MCP server for Claude Code
* runs `doctor`, whose checks may warn on a fresh machine ([which ones](/reference/cli-capture#outerlayer-doctor))
It changes nothing you wrote by hand, and it leaves the new files uncommitted.
**Or set up with your agent.** Open Claude Code in your checkout and paste this prompt. The agent hands you each link to approve. It never prints a token.
```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 `npx @outerlayer/cli 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
`npx @outerlayer/cli login --check `, with the id it printed, until it
stops exiting 75.
2. Then run `npx @outerlayer/cli 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
`npx @outerlayer/cli connect --factory /`.
3. 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.
```
You run `connect` yourself only when `init` prints a link to link the repository. With `--factory`, `connect` uses the factory you name. Without it, `connect` picks a factory by itself when only one fits, and otherwise asks on a terminal. Without a terminal, as under an agent, it exits 1 and lists each `--factory` value to pass. If the repository is not linked to the factory yet, `connect` prints the link to the factory's Work page and exits 2. Link it there in step 1, then run `connect` again.
**Then commit and merge the new files.** `init` writes your policy and skills to `.outerlayer/`, and adds Claude Code files beside them ([which files](/reference/cli-capture#outerlayer-init)). Commit them all and merge them to the branch your pull requests target. Policy is read from each pull request's base branch, so until then no check runs. `init` and `connect` both print a reminder to commit and push `.outerlayer/` while it holds uncommitted files.
On a machine with no browser, choose **No browser on that machine?** at the bottom of the step. It makes a key and fills it into the commands.
Every option and check: [Capture commands](/reference/cli-capture) and [Cloud commands](/reference/cli-cloud#outerlayer-connect). `init --local` installs the hooks only.
The panel's third step is **Add your first issue**. It opens a dialog listing the open issues of the connected repository. A connected tracker is a second source in the same dialog. Choose **Build** beside your issue. A host builds it.
The issue is now a work item, and the factory gives it **a number of its own**. Issue 42 might become item 7. From here on, 7 names the item on the Work page. The issue number never does.
The item's page opens with that number in its heading.
Stay on the item's page. Its **Sessions** list shows the host's session as it runs. When the build finishes, the page shows the pull request the host opened.
This step ends when the item's page shows the pull request and its evidence rows on its **Checks** tab. Open the session to read every turn, the tools it called and what it cost.
No host running? The item waits. On the item's **Activity** tab, expand **Run it yourself** to build it in a session of your own. [Launch a session](/launch-a-session) covers that session.
## What gets uploaded
A session on your machine uploads in full when it belongs to a work item. API keys and tokens are redacted on your machine before anything leaves. [What leaves your machine](/what-leaves-your-machine) lists everything that uploads.
To see what would go before it goes, run `npx @outerlayer/cli sync --dry-run`. It prints one row per session and makes no network calls.
## What happens from now on
Every issue you add gets a number. Choose **Build** beside it in the add dialog, and a host builds it. The session, the pull request and its checks land on the item's page. You approve the item, or send it back, from there.
## If the build does not start
The item's page says whether a host has taken it. An item no host has taken stays queued. Check that a runner is running for your factory: see [Run work on your machines](/run-work-on-your-machines). Or build it yourself with **Run it yourself** on the item's **Activity** tab.
To take an item off the Work page: `npx @outerlayer/cli work remove --item 7 --reason "opened by mistake"`.
## Next steps
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.
Self-hosting is coming soon.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.