> 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
* **A Kerno account**: sign up at [kerno.io](https://www.kerno.io/)
* **A supported backend language**: see [Supported Technologies](/docs/references/supported-technologies.md)

### Set up Kerno with your agent

Kerno is driven by your coding agent, so let your agent install it. Paste this into any MCP-capable coding agent and it will install the CLI, bind Kerno to your repository, register the MCP server, and configure your environment.

```
Set up Kerno for this repo: install the CLI, bind it to this workspace, register MCP with my coding tool,
then configure the environment until it is ready to run endpoint tests. Don't run any tests.

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.

If the kerno plugin is installed and /install-kerno resolves, run that instead.

Preflight: kerno --version, docker info, git repo. Kerno needs Node.js 18+, npm, Docker running, a git repo,
and a Kerno account from kerno.io. If any is missing, stop and tell me.

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

kerno login opens a browser and blocks: pause and wait for me to confirm.

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. kerno doctor --clean fixes an orphan or inconsistent agent.

Ask me which MCP host and which scope, project or user, before registering, and infer neither from the tool
you are running in. Register at one scope only, merging rather than overwriting other servers.

Then allowlist Kerno before calling any tool. A single task runs many Kerno 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. 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 Auto-review. Use the server id you registered if it isn't "kerno".

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. Tell me what it found.

Nothing warns you about this: any stop, restart or workspace switch kills the MCP session even on the same
port. Re-parse the URL and reconnect.

Then configure the environment per Kerno's tool guidance. Record the workspace path, host, scope, app URL and
DB wiring in AGENTS.md, or CLAUDE.md or .cursor/rules. Stop at ready_for_endpoint_test, then tell me what is
configured and what you couldn't do.
```

{% hint style="info" %}
The prompt stops for you in four places: signing in, choosing your MCP host, choosing the scope to register at, and approving the allowlist change. Those are the decisions an agent should not make on your behalf.
{% endhint %}

### 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.

### Hand it to your agent

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

> "Set up Kerno for this project."

Your agent checks whether Kerno is running, sees which applications it found in your repository, and continues from there. If Kerno is not reachable it says so rather than guessing.

### What's next

Kerno does not yet know where your application runs. See [Start the environment](/docs/guides/start-the-environment.md) for what your agent needs from you to point Kerno at your running app.

### Resources

<table 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><i class="fa-comment-question" style="color:$info;">:comment-question:</i> <strong>Support</strong></td><td>Get help from the Kerno team.</td><td><a href="https://discord.gg/k8yA9tZdP9">https://discord.gg/k8yA9tZdP9</a></td></tr><tr><td><i class="fa-lightbulb" style="color:$info;">:lightbulb:</i> <strong>FAQs</strong></td><td>Get answers to common questions.</td><td><a href="/pages/zJKOG1wiwndWnBdcDH4o">/pages/zJKOG1wiwndWnBdcDH4o</a></td></tr><tr><td><i class="fa-shield-check" style="color:$info;">:shield-check:</i> <strong>Security</strong></td><td>Learn how Kerno handles your code and data.</td><td><a href="/pages/a868OKb6TDxWBmJlCO1H">/pages/a868OKb6TDxWBmJlCO1H</a></td></tr></tbody></table>