> 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/references/ports-and-file-paths.md).

# Ports and file paths

This is the reference for the network ports and filesystem paths Kerno uses on your machine.

### Ports

| Service                            | Default port | Override             |
| ---------------------------------- | ------------ | -------------------- |
| 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`.

{% hint style="warning" %}
Treat the defaults above as documentation, not as addresses to hard-code. Kerno reuses the default ports across restarts when it can, and falls back to a free port only when a default is unavailable, so the actual port can differ. Always copy the URL from your terminal rather than reusing one from an old config file.
{% endhint %}

### File paths

Kerno uses these locations on your filesystem.

#### `~/.kerno/`

Installed agent binaries, runtime state, and per-workspace data.

| Path                                            | Purpose                                                                 |
| ----------------------------------------------- | ----------------------------------------------------------------------- |
| `~/.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`, `agent.version` and `agent.org`, the organization the agent signed in with.

{% hint style="info" %}
These exist only while the agent is up. If you go looking for `mcp.port` and it is not there, the agent is not running. That is expected.
{% endhint %}

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

| Path                                 | Purpose                                                                                                                                           | Committed   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `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](/docs/core-concepts/environment-setup.md#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 |

{% hint style="warning" %}
**`config.yaml` is committed.** Put real secret values in `.kerno/.env`, which Kerno gitignores for you. `config.yaml` records only the *name* of the environment variable each secret uses, so it is safe to review in a pull request alongside your code.

Kerno merges `.env` into the sandbox environment when a test runs, and a value there overrides one of the same name in `config.yaml`.
{% endhint %}

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

```yaml
# .kerno/config.yaml
applications:
  payments-api:
    target-environment: "local"
    sut:
      input-url: "http://localhost:8081"
    infrastructure:
      postgres:
        access: "direct"
        env:
          DATABASE_URL: "<set in .kerno/.env>"

  orders-api:
    target-environment: "local"
    sut:
      input-url: "http://localhost:8082"
    infrastructure:
      postgres:
        access: "direct"
        env:
          DATABASE_URL: "<set in .kerno/.env>"
      redis:
        access: "none"
        reason: "Shared with staging, so Kerno leaves it alone"
```

| Key                     | What it sets                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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](/docs/references/supported-technologies.md#supported-external-dependencies) 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](/docs/core-concepts/custom-rules.md) 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](/docs/core-concepts/environment-setup.md#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.

{% hint style="info" %}
The `env` block names the variables. Put the real values in `.kerno/.env`, which Kerno gitignores for you and merges in when a test runs, overriding anything of the same name here.
{% endhint %}

**Per application**

| Path                                       | Purpose                                                                                                                       | Committed |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | --------- |
| `scenarios/endpoints/<METHOD>/<path>/`     | One folder per entry point, holding its scenarios. See [Anatomy of a Kerno test](/docs/references/anatomy-of-a-kerno-test.md) | 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       |
| `scenarios/flows/<flow>/`                  | One folder per [user flow](/docs/core-concepts/user-flows.md), holding the flow's record and its test                         | 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.

| Path                                | Purpose                                                    |
| ----------------------------------- | ---------------------------------------------------------- |
| `/tmp/kerno/scenario-workspace/...` | Working directory for scenario planning and implementation |

#### `$TMPDIR`

| Path                                  | Purpose                                                         |
| ------------------------------------- | --------------------------------------------------------------- |
| `$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:

```bash
kerno uninstall
```

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.