---
title: "Get started with onboarding"
description: "From sign-up to a first task and review in six steps. An agent finishes them with overlane onboarding or the onboarding tool; the web app is the override."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with onboarding

Onboarding takes a new account to a first task and a first review. It has six steps, and the web app, `overlane init`, `overlane onboarding` and the `onboarding` MCP tool use the same names for them. Progress is saved on the server after every step, so an agent or a person can stop, switch to another browser, device or terminal, and continue at the same step.

## An agent finishes it

An agent with a team token needs no person for any step:

```sh
overlane onboarding status                      # the six steps, their state and the next command
npx overlane init                               # sign-up, agents and repo
overlane onboarding advance first-task          # after a task was submitted
overlane onboarding review                      # read the first review
overlane onboarding advance first-review        # after a review ran
overlane onboarding invite pat@example.com      # optional; finishes the invite step
```

`first-task` and `first-review` finish only when a real record exists. The server looks for a task of your team that was submitted or verified, and for a review run of your team. A bare call is refused with `evidence_required` and the command to run first, and the records that backed a finished step are shown by `overlane onboarding status`. A person finishing a step in the web app attests for themselves.

`overlane context` shows `onboarding` and suggests `overlane onboarding status` first while onboarding is not complete. The same operations are in the `onboarding` tool (`status`, `advance`, `review`, `invite`).

```js run
const names = ["sign-up", "agents", "repo", "first-task", "first-review", "invite"];
assert.deepEqual([...STEP_NAMES], names);
```

| Step | What you do | What it changes |
| --- | --- | --- |
| `sign-up` | Create your workspace with an email address. | Creates your workspace. Nothing else yet. |
| `agents` | Pick the coding agents and bots you use and run each one's connect command. | Registers the Overlane plugin or connector in that client. Overlane stores no vendor token. |
| `repo` | Choose a native Overlane repository, or connect GitHub by installing the GitHub App on a repository. | Creates one project per repository you pick. |
| `first-task` | An agent creates, works and submits a real task (the web app also offers a sample run). | Needs a submitted or verified task of your team when an agent completes it. |
| `first-review` | An agent runs a real review and reads it (the web app shows a labelled sample until one exists). | Needs a recorded review run of your team when an agent completes it. |
| `invite` | Add colleagues by email, or skip. | Sends each person an email with a link to join. It never blocks you. |

## In the web app

Open the web app at `overlane.app/onboarding/` and choose Sign up. Each step shows what it needs and what it changes before you do anything, and a step that fails shows a repair action next to the problem. Earlier steps stay done while you repair a later one.

The web app shows a sample run and a sample review while there is no real record yet, marked "Sample" on screen so you can tell them from the real thing. Once an agent has submitted a task and run a review, the first review shows the live one.

## In the terminal

[Quick start](/quick-start/) covers this path in full. `npx overlane init` covers the first three steps for the project you are standing in, and prints the step names as it goes, so the web app opens at `first-task`.

```sh
npx overlane init --dry-run
npx overlane init
```

Then start your first task from the terminal, or continue in the web app:

```sh
overlane task new "Add a CONTRIBUTING.md"
```

See [overlane init](/cli/init/) for every flag.

## Connect each agent and bot

Every client signs in with its own screen. Overlane never asks for a subscription token, a ChatGPT session token or a coding-agent API key, and no onboarding screen has a field for one.

| Client | Command or action |
| --- | --- |
| Claude Code | `npx overlane init --agents claude` |
| Codex | `npx overlane init --agents codex` |
| Grok Build | `overlane client install grok` |
| Cursor | `overlane client install cursor` |
| Gemini CLI | `overlane client install gemini` |
| ChatGPT Dots and other bots | Add Overlane as a connector in the bot's own app and approve the Overlane sign-in screen. |

The adapters are described in [overlane client install](/cli/client-install/). After you run a command, choose Check connection in the web app. The plugin reports in to the service, and the step moves on.

## Connect a repository

**Native repository.** A repository hosted by Overlane, so you need no other account. Onboarding creates the project; create its repository with `overlane repo create <name>` and push to it.

**Or connect GitHub.** Choose Install the GitHub App, pick the repositories to share, and come back to choose one. Overlane creates a project for it. The app can read the repositories you share and no others, and you can change that on GitHub at any time.

## When a step fails

A failed step stays where it is, keeps the earlier steps done, and names one repair action. The same ids are used by the web app and the service.

```js run
assert.equal(FAILURE_REPAIRS["install-cancelled"].id, "retry-install");
assert.equal(FAILURE_REPAIRS["agent-not-connected"].id, "retry-connect");
assert.equal(Object.keys(FAILURE_REPAIRS).length, 8);
```

| Repair action | When it appears | What to do |
| --- | --- | --- |
| `retry-sign-in` | Sign-in was cancelled. | Try again, or use the email link. |
| `retry-connect` | The agent has not reported in. | Run the plugin command shown, finish the agent's own sign-in, then check again. |
| `reauthorise` | The agent's own sign-in was denied. | Approve access in the agent, then check again. |
| `retry-install` | The GitHub App install was cancelled, or the organisation has not approved it yet. | Retry the install, or use a native repository. |
| `pick-another-repo` | The repository could not be read. | Pick another, or re-run the install and share more repositories. |
| `retry-task` | The sample run did not finish. | Retry it, or pick a smaller template. |
| `reload-review` | The sample review is not ready. | Reload it. |
| `retry-invite` | An email to a colleague could not be sent. | Check the address and try again, or skip this step. |

Still stuck? Run `overlane doctor` to check each agent's readiness. It prints one state per agent and the next repair command.

## Teams and roles

People you add join as members. Roles can be changed later; see [teams and roles](/teams-and-roles/). Each person has their own onboarding progress inside a shared team, and an agent's progress is its member's.

Source: https://docs.overlane.app/getting-started/onboarding/index.mdx