> For the complete documentation index, see [llms.txt](https://docs.codna.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codna.ai/reference/operations.md).

# Operations

Codna runs a small local runtime — a compiled agent-core sidecar bundled in the wheel — that the agent talks to. It starts on demand and is owned per checkout. You rarely manage it by hand; this page covers when you do.

## Health check

```bash
codna status
```

`codna status` never spawns anything and never errors. It reports:

| Line            | Values                                                  |
| --------------- | ------------------------------------------------------- |
| `engine`        | `running` / `stopped` / `unknown`                       |
| `telys runtime` | `ready (<source>)` / `not installed — run codna login`  |
| `telys license` | the license source / `none` / `misconfigured`           |
| `engine key`    | `configured` / `missing (set CODNA_API_KEY)`            |
| `provider key`  | `configured` / `missing — run codna key set <provider>` |

## Full diagnostic

```bash
codna doctor                 # inspect the runtime (JSON)
codna doctor --start-stack   # ensure the sidecar is running
codna doctor --stop-stack    # stop the sidecar
```

The key field in the JSON is `status`:

| `status`              | Meaning                                                                | Recovery                     |
| --------------------- | ---------------------------------------------------------------------- | ---------------------------- |
| `not_running`         | No sidecar is listening.                                               | `codna doctor --start-stack` |
| `healthy_owned`       | Healthy and owned by this checkout.                                    | none                         |
| `unhealthy_owned`     | Owned but failing health checks.                                       | restart                      |
| `stale_codna_sidecar` | A healthy sidecar that can't be reused here (see `stale_reasons`).     | restart                      |
| `port_collision`      | Another process holds the port, or the listener isn't a Codna sidecar. | free the port                |

When a restart or start is needed, the report includes the exact `codna_command` to run.

## Ports and the sidecar

| Port    | Role                               |
| ------- | ---------------------------------- |
| `18600` | Engine (`http://127.0.0.1:18600`)  |
| `18601` | Sidecar (`http://127.0.0.1:18601`) |

The sidecar is a native binary staged into the wheel at `_agent_core_runtime/codna-sidecar` and launched directly — no Node or Bun required. (A source checkout without the binary falls back to a Node + Bun dev path; installed wheels never need it.) It listens on loopback only and is health-gated on `/health` and `/ready`.

## Environment variables

| Variable                                 | Default     | Effect                                                               |
| ---------------------------------------- | ----------- | -------------------------------------------------------------------- |
| `CODNA_RUNTIME_ROOT`                     | `~/.codna`  | Root for runtime state, logs, and the key index.                     |
| `CODNA_PORT_BASE`                        | `18600`     | Base port; engine = base, sidecar = base + 1. Range `[1024, 65534]`. |
| `CODNA_SIDECAR_BINARY`                   | *(bundled)* | Explicit path to the compiled sidecar.                               |
| `CODNA_DISABLE_KEYCHAIN`                 | *(off)*     | `1`/`true` disables OS-keychain access; keys come from env only.     |
| `CODNA_HTTP_MAX_RETRIES`                 | `2`         | Retries for engine HTTP calls.                                       |
| `CODNA_AGENT_CORE_READY_TIMEOUT_SECONDS` | `120`       | Sidecar readiness timeout (clamped `5`–`300`).                       |

{% hint style="info" %}
Codna runs its engine in-process from the bundled runtime — there's no engine URL or server to configure.
{% endhint %}

## State on disk

Under `CODNA_RUNTIME_ROOT` (default `~/.codna`):

* `runtime/local-stack.json`, `runtime/local-stack.lock` — runtime state and lock.
* `logs/` — rotating sidecar logs.
* `keys/keychain-index.json` — the non-secret index of stored provider keys (values live in the OS keychain).

Device login state lives under `~/.telys/`; per-repository memory lives in each repo's `.codna-memory/`.

## See also

* [CLI Reference](/reference/cli.md) — full `codna doctor` / `codna status` flags.
* [Configuration](/reference/configuration.md) — the complete environment and `codna.yaml` reference.
* [Troubleshooting](/reference/troubleshooting.md) — common failures and fixes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.codna.ai/reference/operations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.