Ctrlk
Back to Kerno.io
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 running, and a git repo.

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

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

If kerno init reports a problem with the organization or its key, stop and ask me which organization to use, then re-run kerno init -w "<path>" --org <name or id>. 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. Don't use a healthcheck, which 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. 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

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:

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.

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.

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.

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.

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:

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 with you. See Calibration. The setup page in the Portal shows each step as it completes.

What's next

Test a User Flow

Learn how to test a key journey through your app end to end

Configure the Kerno Test Environment

Learn how to connect Kerno to your running application

Create Baseline Tests for your Entry Points

Learn how to generate baseline tests for an entry point

Last updated