> 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

### Ports

| Service                                            | Default port | Override             |
| -------------------------------------------------- | ------------ | -------------------- |
| Agent REST API (used by the IDE extension and 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 four 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/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                          |

**Runtime state files.** While the agent is running, `~/.kerno/` also holds `agent.pid`, `agent.port`, `mcp.port`, `agent.workspace` and `agent.version`.

{% 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, not a broken install.
{% 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 at your repository root. In a monorepo, scenarios live under each app's own directory while configuration and hooks stay at the root.

Kerno auto-writes a `.kerno/.gitignore` covering `hooks/*`, `mcp-jobs/*`, `config.yaml` and `config.yml`, so credentials never reach your history. The rest of `.kerno/` is intended to be committed alongside your code.

**At the workspace root**

| Path                    | Purpose                                                                       | Committed |
| ----------------------- | ----------------------------------------------------------------------------- | --------- |
| `config.yaml`           | Your local configuration, including datastore credentials                     | no        |
| `default.config.yaml`   | Shared defaults for the team                                                  | yes       |
| `.gitignore`            | Written by Kerno                                                              | yes       |
| `hooks/`                | Git hooks Kerno installs                                                      | no        |
| `mcp-jobs/<job_id>.log` | Logs for in-flight async jobs                                                 | no        |
| `CHANGES_DETECTED.md`   | Endpoints impacted by your current changes, when change detection is wired up | yes       |

**Per application**

| Path                                   | Purpose                                                                                                             | Committed |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------- |
| `scenarios/endpoints/<METHOD>/<path>/` | Generated scenarios (`*.scenario.ts`) and their descriptions (`*.scenario.md`), grouped by endpoint                 | yes       |
| `analysis/`                            | Kerno's analysis output, reused as context across runs. Markdown reports plus per-endpoint security recipes as JSON | yes       |

#### `/tmp/kerno/`

Temporary working directories.

| Path                                | Purpose                                                          |
| ----------------------------------- | ---------------------------------------------------------------- |
| `/tmp/kerno/scenario-workspace/...` | Working directory for scenario planning and implementation       |
| `/tmp/kerno/compose/...`            | Compose projects, present only while a stack Kerno started is up |

#### Sandbox working directory

Kerno's scenario sandbox uses `$TMPDIR/kerno/sandbox/<project>` for its own working files.

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