Skip to content

Getting Started

Jump to bottom
Archi edited this page Oct 20, 2026 · 2 revisions

Getting started

This page takes you from an empty machine to a first card running on your own repository. You will start the control plane locally, pair a runner, connect a project and run one piece of work. It takes about 15 minutes.

flowchart LR
  a["1 · Start the<br/>control plane"] --> b["2 · Create<br/>the admin"] --> c["3 · Pair<br/>a runner"] --> d["4 · Connect<br/>a project"] --> e["5 · Hook up<br/>Claude Code"] --> f["6 · First<br/>card"]
Loading

Before you begin

You need Why
Bun 1.4.0+ and Node.js 24+ to build and run the API and the web app
Docker for PostgreSQL and Redis in local development
On the machine with your repositories: tmux, git, a signed-in gh and Claude Code the runner launches and watches agents with them

The control plane and the runner can live on the same machine. That is the easiest way to try Nautelle.

1. Start the control plane

git clone https://github.com/AndreyBegma/Nautelle && cd Nautelle
bun install

cp docker/.env.example docker/.env
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

bun run db:setup     # PostgreSQL on :5421, Redis on :6421, migrations, seed

The example environment files already agree with each other. The passwords in docker/.env must match DATABASE_URL and REDIS_URL in apps/api/.env.

2. Create the first admin

The seed creates no users. Create the first admin from the command line, then start everything:

bun run admin:create
bun run start:dev    # API http://localhost:8180 · web http://localhost:3517

Open http://localhost:3517 and sign in. curl http://localhost:8180/health checks the API.

Note

Everyone who registers after the first admin waits for an admin to approve them and assign a role. See Security and access.

3. Pair a runner

  1. In the web app, open Admin › Runners › Add runner and copy the one-time code. It expires after 10 minutes.

  2. On the machine that holds your repositories, install the runner and pair it:

    brew install andreybegma/tap/nautelle-runner   # or: npm i -g nautelle-runner
nautelle-runner pair --server http://localhost:8180 --code XXXX-XXXX --allow-root ~/dev
nautelle-runner install-service

  3. Start the service with the command install-service prints. The runner appears as online under Admin › Runners.

--allow-root names the folders your projects live in. The runner refuses to watch anything outside them. The runner guide covers the other options and the local security policy.

Tip

Every Nautelle server has a public /install page with the same steps, with the server address already filled in.

4. Connect a project

  1. Open Projects › Connect project.
  2. Pick the runner and enter the absolute path of a git repository under an allowed root.
  3. Nautelle asks the runner to inspect it. The runner detects the GitHub origin, the base branch, any Code Sentinel configuration and where the project's docs live. Review the result and connect.

Only GitHub repositories can be connected.

5. Hook up Claude Code

Install the Nautelle plugin into the Claude Code profile the runner uses. This makes your terminal sessions visible and gives agents the Nautelle MCP tools:

nautelle-runner profiles                      # find the profile key
nautelle-runner setup claude --profile <key>

Restart any open Claude Code sessions. Project › Settings › Sessions shows a checklist of what is done and what is still left. See Claude Code integration.

6. Run your first card

  1. Open the project's Board and choose New work.
  2. Describe the change in one sentence, in any language, and answer the interview questions. To skip the rest, choose Enough — generate.
  3. Review the candidate card in Drafts and accept it. It moves to To Do.
  4. Choose Run, then pick a profile and a model. Nautelle recommends one.
  5. Watch the card move to In progress. A draft pull request appears while the agent works. When it finishes, the card moves to Finished with a ready pull request.
  6. Accept the card to merge, or leave it to auto-merge if the project allows it.

The full lifecycle is in How work flows.

Next steps

Nautelle · Website · Discord · Engineering docs · MIT

Home

Start

Work

Cost and health

Surfaces

Operate

Reference

Clone this wiki locally