Ports and file paths
This is the reference for the network ports and filesystem paths Kerno uses on your machine.
Ports
Agent REST API (used by the CLI)
8085
AGENT_PORT env var
MCP server (used by coding agents)
8086
MCP_PORT env var
Both ports listen on localhost only and are not reachable from other machines on your network.
If the default port is taken, Kerno auto-allocates a free one. The actual port is printed by kerno init.
File paths
Kerno uses these locations on your filesystem.
~/.kerno/
Installed agent binaries, runtime state, and per-workspace data.
~/.kerno/assets/agent/{version}/aicore-agent/
Installed agent distribution
~/.kerno/assets/runtime/{version}/custom-jre/
Custom JRE bundled with the agent
~/.kerno/assets/scip/
Code indexers and the Node runtime they need
~/.kerno/assets/index/
Type packages downloaded for code indexing
~/.kerno/agent/
Agent working directory, cleared on each agent start
~/.kerno/workspaces/<workspace>/
Per-workspace snapshots, indexed data, prompt cache, and logs
~/.kerno/agent.stdout.log
Agent startup output, the first place to look when the agent won't boot
~/.kerno/state.json
CLI state, including your selected organization
~/.kerno/cli-update-check.json
When the CLI last checked npm for a newer version
~/.kerno/cli.installed
Marks that the CLI has run on this machine
Runtime state files. While the agent is running, ~/.kerno/ also holds agent.pid, agent.port, mcp.port, agent.workspace and agent.version.
Credentials. Your login tokens are held in the OS keychain (macOS Keychain, the Linux Secret Service via secret-tool, or Windows Credential Manager). Only when no keychain is available do they fall back to ~/.kerno/secrets.json, readable only by you.
.kerno/ (in your repository)
Kerno creates this in the workspace your agent works in, normally your repository root. In a monorepo, scenarios live under each app's own directory. A nested directory your agent uses as its workspace gets its own .kerno/config.yaml, and settings saved there live there.
Kerno auto-writes a .kerno/.gitignore containing one entry, .env, so your secret values stay out of your history. The rest of .kerno/, including config.yaml, is intended to be committed alongside your code.
At the workspace root
config.yaml
How Kerno reaches your application, and the name of the environment variable holding each dependency's credentials. config.yml also works
yes
.env
The real values for the variables config.yaml names, one VAR=value per line
no
.gitignore
Written by Kerno, containing .env
yes
healthcheck.<local/remote>.ts
The environment healthcheck calibration generates from your infrastructure. Yours to edit
yes
CHANGES_DETECTED.md
Entry points impacted by your current changes, written by a changed-scope run
yes
memory/
What Kerno has learned about your codebase, one Markdown file per record plus a README, for review in pull requests
yes
config.yaml.unreadable-<timestamp>
A config.yaml Kerno could not parse, moved aside before it writes a new one
your choice
monitor-endpoint-test-job.sh
A helper script your agent uses, kept out of git
no
settings.yaml
Optional. Each key: value under its agent: section is passed to the agent as an environment variable when the CLI starts it
your choice
What config.yaml holds
One file in the workspace covers every application Kerno found there, keyed by application id under applications. Each entry carries that application's own URL and its own dependency access, which is how a monorepo runs several services at once.
target-environment
local when the application runs on your machine, remote when it runs somewhere you reach
sut.input-url
Where that application is listening
infrastructure.<kind>
One entry per component the application talks to. Its key is one of postgres, mariadb, mysql, mongodb, redis, kafka, rabbitmq, azure-servicebus, aws, aws-sqs, dynamodb, clickhouse, azurite, s3, zitadel, cognito or bifrost, and Kerno ignores any other key
<kind>
An older form some saves still write directly under the application, such as postgres: followed by its variables. It reads as access: direct, and an infrastructure entry for the same kind takes precedence
http-services
Other HTTP services the application calls, each with a base-url and an openapi-spec. Also allowed at the top level
test-generation
Custom rules for that application
A key Kerno does not define is kept as written and has no effect, so a typo in a hand-edited key changes nothing. When your agent saves settings, Kerno names any such keys.
At the top level, beside applications, a calibration block records the outcome of calibration, either calibrated or declined, with the date and a short note. Calibration writes it, and your agent reads it to know the repository is already calibrated.
Each infrastructure entry sets access to one of two values. Use access: direct with an env block naming the variables Kerno needs, and it will connect to that component. Use access: none on its own, with an optional reason, to record that the component exists and have Kerno leave it alone.
Per application
scenarios/endpoints/<METHOD>/<path>/
One folder per entry point, holding its scenarios. See Anatomy of a Kerno test
yes
scenarios/endpoints/.../*.scenario.md
Each scenario in plain English. The one to read
yes
scenarios/endpoints/.../*.scenario.ts
Each scenario as executable TypeScript
yes
scenarios/endpoints/.../preconditions.ts
Checks that run before the entry point's scenarios
yes
scenarios/endpoints/.../plan.json
The plan the Markdown is rendered from
yes
scenarios/endpoints/.../report.json
Results from the most recent run
yes
analysis/
Per-entry-point security recipes as JSON, reused as context across runs
yes
criticality.json
The entry points your team marked critical in the Portal, synced into the repository
yes
/tmp/kerno/
Temporary working directories.
/tmp/kerno/scenario-workspace/...
Working directory for scenario planning and implementation
$TMPDIR
$TMPDIR/kerno/sandbox/<project>
The scenario sandbox's own working files
$TMPDIR/code-index-<repo>-<commit>/
Per-commit checkouts used to build the code index
$TMPDIR/kerno-tool-results/
Large tool results set aside during a run, readable only by you
Agent skills (in your repository)
Kerno installs its agent skills at .agents/skills/kerno-*, with links to them at .claude/skills/kerno-*. It keeps them out of git by adding .agents/skills/*, the links and .kerno/monitor-endpoint-test-job.sh to .git/info/exclude. The first line covers the whole folder, so any other skill you keep in .agents/skills/ is ignored too.
Removing Kerno
To stop the agent and remove the installed binaries, run:
This stops the running agent and clears ~/.kerno/assets/, which includes the agent distribution, the bundled JRE, and the code indexers.
Other state is preserved unless you delete it manually: ~/.kerno/workspaces/, your repository's .kerno/ directory, anything under /tmp/kerno/, and your login credentials in the OS keychain.
Last updated