> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/getting-started/quickstart.md).

# Quickstart

Install Kerno and connect it to your AI coding agent.

### Prerequisites

* **Docker** (or Podman): must be installed and running
* **Node.js 18+**: required to run the Kerno CLI
* **Git**: your project must be a git repository

### Set up Kerno with your agent

Kerno is driven by your coding agent, so let your agent install it. Paste this into any coding agent and it will install the CLI, bind Kerno to your repository, register the MCP server, and kick off onboarding

```
Set up Kerno for this repo: install the CLI, bind it to this workspace, register MCP with my coding tool, then trigger workspace analysis and list the available apps for me to choose from. Follow the Kerno MCP's instructions throughout. Don't run any tests, and don't set up the environment yet.

Read rather than improvise. kerno init prints what you need, and once MCP is live every Kerno tool carries a What/When description saying what to call next. Follow those. The commands below are the happy path; if kerno init prints something different, its output wins.

Prerequisites that must already exist. If any of these is missing, stop and tell me: Node.js 18+, npm, Docker or Podman running, and a git repo.

  npm install -g @kerno/cli
  kerno login
  kerno init -w "<absolute path to this repo>"

Don't run kerno login yourself. It renders an interactive terminal UI and fails in an agent shell with "Raw mode is not supported on the current process.stdin". Tell me to run ! kerno login in the prompt myself, then pause and wait for me to confirm I've logged in before continuing. If I'm working over SSH or in a container with no browser, tell me I can log in with kerno login --api-key instead, or by setting KERNO_API_KEY.

Run kerno init -w even if something seems to be listening already, never two at once, then use the workspace, port and registration snippet it prints verbatim. The port can change when its usual one is taken, so never reuse one from docs, an old config, or memory. In an agent shell, kerno init prints the port and registration snippet as plain text. If they are missing, read the port from ~/.kerno/mcp.port and build the endpoint as http://localhost:N/mcp. kerno doctor --clean fixes an orphan or inconsistent agent.

If kerno init says no organization has been chosen, stop and ask me which organization to use, then re-run kerno init -w "<path>" --org <name or id>. If it says my API key is for a different organization, show me its message and wait for me to sign in again as it describes. Never edit ~/.kerno/state.json by hand.

Register with the host you are running in, and ask whether I want a different one. Register at one scope only, project or user, and merge rather than overwrite other servers. Then allowlist Kerno before calling any tool. A single task runs many calls, including repeated status and job polling, so without this I am clicking approve every few seconds. Explain that to me, show me the change, and apply it once I accept. If it's already present, tell me and move on. Claude Code: "mcp__kerno__*" in permissions.allow in .claude/settings.json or ~/.claude/settings.json. Codex: default_tools_approval_mode = "approve" under [mcp_servers.kerno] in ~/.codex/config.toml. Cursor: no file, tell me to set Run Mode to Auto-review.

Registering the server does not load its tools into a session that was already running. Before you try to call anything, expect the kerno_* tools to be absent, and tell me to reconnect: in Claude Code run /mcp, select the server, and reconnect, or restart the tool. A "Connected" line from claude mcp list is not proof your current session can call the tools, because that check opens its own session.

Verify with kerno_get_applications; that succeeding means connected.

If Kerno stops, restarts or switches workspace, take the endpoint from kerno init's output and reconnect with it if the kerno_* tools are gone from your session.

Once connected, let Kerno finish analyzing the workspace. The first analysis can run for several minutes and outlast a single tool call, which looks like a hang but isn't. Calling again with the same arguments is safe and picks up the same run. Don't sync the workspace or clear the cache to unstick it, because that restarts the analysis from scratch.

Then list the apps it found and present them to me so I can choose which one to test. If there is more than one, mark which one looks like the backend, and once I pick, name that one app in every later Kerno call. Calls without an app analyze every app in the repo, and each app gets its own sandbox container. Stop there and follow the Kerno MCP's tool guidance for what comes next, including the usage note it asks you to add to this repo's agent instruction files.

```

### Install manually

#### 1. Install the CLI

```bash
npm install -g @kerno/cli
kerno login
```

`kerno login` opens a browser to authenticate you. On a machine with no browser, such as over SSH or in a container, run `kerno login --api-key <key>` or set `KERNO_API_KEY`. Once signed in, return to your terminal and point Kerno at your repository:

```bash
kerno init -w /absolute/path/to/your/repo
```

Or run `kerno init` from inside the project directory. On first run this downloads the Kerno agent, which takes a moment. It then binds the agent to that workspace and prints the MCP server URL, along with a ready-made registration command for Claude Code and a config snippet for Cursor.

Each repository runs under its own Kerno organization. The first time you run `kerno init` in a repository, it asks which organization to use there and remembers your answer. Add `--org <name or id>` to choose it up front, for example when no terminal is available to ask in. If the agent is running for a different organization, `kerno init` restarts it for this one.

{% hint style="info" %}
`kerno init` binds the agent to **one repository root**. The agent then serves that root and every directory nested under it as separate workspaces, so a monorepo's applications are all reachable from the one agent, selected per call by `workspace_path`. To point it at a repository **outside** that root, prefer `kerno stop` followed by `kerno init -w <other-path>`, which cancels the current workspace's in-flight work before shutting down. In a terminal, `kerno init -w <other-path>` alone asks whether to stop the running agent and start there. From an agent shell, add `--force-switch` to switch in one step, though it stops the old agent while its work is still running.

If switching workspaces or restarting the agent moves Kerno to a different port, update your coding tool with the URL `kerno init` prints.
{% endhint %}

#### 2. Connect MCP

Use the command or config snippet that `kerno init` printed. It already contains the correct URL, and any MCP-compatible coding tool can connect to it.

{% hint style="info" %}
Kerno keeps the same MCP port across restarts, 8086 by default, so your config keeps working. If another program holds that port, Kerno picks a free one, and `kerno init` prints the new URL.
{% endhint %}

Then allow Kerno's tools, or you will approve every call by hand. A single task runs many Kerno calls, including repeated status and job polling.

* **Claude Code:** add `"mcp__kerno__*"` to `permissions.allow` in `.claude/settings.json` for this project, or `~/.claude/settings.json` for every project.
* **Codex:** add `default_tools_approval_mode = "approve"` under `[mcp_servers.kerno]` in `~/.codex/config.toml`.
* **Cursor:** set Run Mode to **Auto-review**, which lets allowlisted MCP tools run without prompting.

### Setup Kerno for your project

Once MCP is connected, ask your agent to take it from here:

```
Use the Kerno MCP to set up Kerno for this project.
```

Your agent checks that Kerno is reachable, asks which applications are in your repository, and picks one to work on. It saves the URL your application runs on and, optionally, credentials for your database and other dependencies, asking you for whatever it cannot find in your repository. Once Kerno reports the environment ready, your agent calibrates Kerno to your repository and asks you to confirm what it found. It then maps your key [user flows](/docs/core-concepts/user-flows.md) with you. See [Calibration](/docs/core-concepts/environment-setup.md#calibration). The setup page in the Portal shows each step as it completes.

### What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Test a User Flow</strong></td><td>Learn how to test a key journey through your app end to end</td><td><a href="/docs/guides/test-a-user-flow.md">How to Test a User Flow</a></td></tr><tr><td><strong>Configure the Kerno Test Environment</strong></td><td>Learn how to connect Kerno to your running application</td><td><a href="/docs/guides/start-the-environment.md">How to Configure the Kerno Test Environment</a></td></tr><tr><td><strong>Create Baseline Tests for your Entry Points</strong></td><td>Learn how to generate baseline tests for an entry point</td><td><a href="/docs/guides/capture-a-baseline.md">How to Create Baseline Tests for your Entry Points</a></td></tr></tbody></table>