Installation Issues

Solutions to Kerno installation issues.

The agent is not starting

• Turn off your VPN. If a VPN is intercepting outbound traffic, Kerno cannot reach LLM providers and will fail to index your codebase or run tests.

• Check the startup log. ~/.kerno/agent.stdout.log records what happened when the agent tried to boot, and is the fastest way to see the real error.

• Sweep orphaned processes. Run kerno doctor --clean to kill stray agent processes and clear inconsistent state files.

• Start clean. kerno reset stops applications, clears workspace caches, and restarts the agent fresh.

My coding agent says the session is unknown

The Kerno agent serves one workspace at a time, and restarting it or pointing it at a different repository ends the current MCP session.

This is expected after kerno reset, kerno stop, or a kerno init --force-switch. Reconnect your coding tool, and copy the new URL from the kerno init output rather than reusing the old one — the port is allocated per session.

kerno init says the agent is bound to another workspace

That is the single-workspace rule. To move the agent:

kerno init -w /absolute/path/to/other/repo --force-switch

kerno status does nothing inside my coding agent

kerno status and the bare kerno shell render an interactive terminal UI, which does not work in a non-interactive agent shell.

From inside a coding agent, use kerno --version and docker info to check the basics, and ask your agent to run a Kerno healthcheck for everything else. The healthcheck runs for around 120 seconds by design, so give it time rather than assuming it has hung.

The port isn't in ~/.kerno/mcp.port

Those files exist only while the agent is running. If agent.pid, agent.port or mcp.port are missing, the agent is not up. Check ~/.kerno/agent.stdout.log.

The indexing process is failing

• Make sure your language stack is supported.

• Kerno indexes git-tracked files. Brand-new files that have never been added to git are not analyzed until you stage or commit them.

• Make sure you don't have multiple projects open inside your IDE.

• Try kerno reset to clear cached analysis and start fresh.

Collecting logs for support

kerno export-logs -o ./kerno-logs.zip

If you encounter issues or have questions, message us on Discord, and we'll gladly help.