> 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

### Prerequisites

* **Docker**: 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, and call kerno_guide for detail. 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 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 dies immediately in an agent shell with "Raw mode is not supported on the current process.stdin", so the browser never opens. Instead, tell me to run ! kerno login in the prompt myself, then pause and wait for me to confirm I've logged in before continuing.

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 is per-session, so never reuse one from docs, an old config, or memory. Be aware that init's port and registration snippet render through the same terminal UI, so in an agent or piped shell the plain output may stop at "Starting agent..." with no port and no registration line. If that happens, don't guess: either re-run under a pseudo-TTY to force the full snippet to render (script -q /dev/null kerno init -w "<path>"), or read the port from ~/.kerno/agent.stdout.log (the line "Kerno MCP server started on port N") and build the endpoint as http://localhost:N/mcp. kerno doctor --clean fixes an orphan or inconsistent agent.

Default to registering with the host you are running in, but confirm r, and ask if I want a different one. Don't infer my preference fromthe tool alone. 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 manypeated status and job polling, so without this I am clicking approveevery 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 [plugins."kerno@kerno".mcp_servers.kerno] in ~/.codex/config.toml. Cursor: no file, tell me to set Run Mode to r id you registered if it isn't "kerno".

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  Verify only with kerno_get_applications.

Verify with kerno_get_applications; that succeeding means connected. Don't use a healthcheck, which blocks 120 seconds and can report a schema error while MCP is fine, and don't use kerno status, which needs a TTY and exits 1 in agent shells even with CI=true.

Also note: any stop, restart or workspace switch kills the MCP session even on the same port. Re-parse the MCP endpoint URL from the registration snippet and reconnect the same way.

Once connected, let Kerno finish analyzing the workspace, then list the apps it found and present them to me so I can choose which one to test. Stop there and follow the Kerno MCP's tool guidance for what comes next.
```

### Install manually

#### 1. Install the CLI

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

`kerno login` opens a browser to authenticate you. 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.

{% hint style="info" %}
The agent serves **one workspace at a time**. To point it at a different repository, prefer `kerno stop` followed by `kerno init -w <other-path>`, which cancels the current workspace's in-flight work before shutting down. `kerno init -w <other-path> --force-switch` does it in one step, but stops the old agent without cancelling what it was doing.

Either way, switching workspaces or restarting the agent ends the current MCP session, even when the port does not change, so your coding tool will need to reconnect.
{% 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="warning" %}
The port is session-specific. Always copy it from your terminal output, never from documentation or an old config file.
{% 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 `[plugins."kerno@kerno".mcp_servers.kerno]` in `~/.codex/config.toml`.
* **Cursor:** set Run Mode to **Auto-review**, which lets allowlisted MCP tools run without prompting.

#### 3. Install the plugin

The Kerno plugin ships the skills and slash commands that teach your agent how to work with Kerno: `/install-kerno`, `/kerno-env`, `/kerno-endpoint-test`, `/kerno-bootstrap`, and `/kerno-help`.

**Claude Code:**

```
/plugin marketplace add kernoio/kerno-mcp-plugin
/plugin install kerno@kerno
```

**Cursor:** Settings → Plugins → Add marketplace → Import from repo → `kernoio/kerno-mcp-plugin` → install `kerno` → reload the window.

**Codex:** `codex plugin marketplace add kernoio/kerno-mcp-plugin`, install from `/plugins`, then start a new session.

### 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. It stops once Kerno reports the environment ready.

### 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>Configure the Kerno Test Environment</strong></td><td>Learn how to connect Kerno to your running application</td><td><a href="/pages/xIm7mmrYCPb7TCXwR6ll">/pages/xIm7mmrYCPb7TCXwR6ll</a></td></tr><tr><td><strong>Create Baselines Tests for your Endpoints</strong></td><td>Learn how to generate baseline tests for an endpoints</td><td><a href="/pages/EMd6jzNA7Nb2CudcRx5J">/pages/EMd6jzNA7Nb2CudcRx5J</a></td></tr></tbody></table>