# Kortix vs OpenCode config

The strict ownership boundary between the manifest and the .kortix/opencode/ config directory.

Canonical page: https://kortix.com/docs/reference/config-boundary

A Kortix project's config has two owners, and the boundary is strict.

- **Kortix owns** the manifest (`kortix.yaml`) and `.kortix/Dockerfile` — what a project is, its sandbox, secrets, triggers, and which agents the platform may launch/authorize.
- **OpenCode owns** `.kortix/opencode/` — how the runtime behaves. `opencode.jsonc` remains the native registry for plugins, MCP servers, providers, models, permissions, and default OpenCode behavior.

The config dir is declared via `opencode.config_dir` (default `.kortix/opencode`); the agent daemon launches OpenCode with `OPENCODE_CONFIG_DIR` pointed there.

In `kortix.yaml`, `agents:` is a map keyed by agent name, and it is **governance only** — `connectors`, `secrets`, `kortix_cli`, `skills`, `workspace`, `enabled`. There is no `model`, `mode`, `description`, `permission`, or `prompt` field on the manifest side at all: every behavioral concern lives in that agent's own `.kortix/opencode/agents/<name>.md` frontmatter and body. The agent's *name* is the only join between the two files — the manifest key must match the `.md` filename. This is a stricter split than it sounds: there's no field on either side that can express the other's concern, so there's nothing to accidentally duplicate.

`agents:` is also deny-by-default in `kortix.yaml`: an agent with no `connectors`/`secrets`/`kortix_cli`/`skills` key gets none of them. Any agent name not declared in the map is fully denied — no connectors, no `kortix_cli` powers, no secrets — though it still runs whatever its `.md` file says.

> **Legacy: kortix.toml**
> v1 projects (`kortix.toml`) express the same governance idea with `[[agents]]` — an array of tables instead of a name→block map, secrets are called `env` instead of `secrets`, and defaults run the other way: an omitted field on a declared agent falls back to permissive per-field defaults rather than "none," and a project with **no** `[[agents]]` section at all skips governance entirely (every agent inherits the launching user's full role). See [kortix.toml](/docs/reference/manifest) for the v1 field table.

## Ownership table

| Concern | Lives in | Read by |
| --- | --- | --- |
| Project metadata (`name`, `description`) | `kortix.yaml` `project:` | Kortix |
| Env / secrets spec | `kortix.yaml` `env:` | Kortix |
| Sandbox base image | `kortix.yaml` `sandbox:` + `.kortix/Dockerfile` | Kortix |
| Where the OpenCode config dir lives | `kortix.yaml` `opencode.config_dir` | Kortix |
| Triggers (cron + webhook) | `kortix.yaml` `triggers:` | Kortix |
| Platform-launchable agents and grants | `kortix.yaml` `agents:` (governance only) | Kortix |
| Channels | Not in the manifest — dashboard/CLI-managed (`kortix channels`). The connector itself (`provider: channel`) is still declared under `connectors:` once you connect one. | Kortix (live routing is the `chat_channel_bindings` table) |
| Agent personas | `.kortix/opencode/agents/<name>.md` | OpenCode |
| Skills | `.kortix/opencode/skills/` | OpenCode |
| Slash commands | `.kortix/opencode/` (commands) | OpenCode |
| Custom tools | `.kortix/opencode/` (tools) | OpenCode |
| Plugins | `.kortix/opencode/` (plugins) | OpenCode |
| MCP servers | `.kortix/opencode/opencode.jsonc` | OpenCode |
| Model / provider config | `.kortix/opencode/opencode.jsonc` | OpenCode runtime; product model pickers should come from the server / LLM gateway catalog |

> **Rule of thumb**
> If it describes the project, the sandbox, when work runs, or what the platform is allowed to launch/authorize, it belongs in `kortix.yaml`. If it describes how OpenCode executes that agent, it belongs under `.kortix/opencode/`.

Full manifest field reference: [the manifest](/docs/reference/manifest). The `.kortix/opencode/` directory follows OpenCode's standard layout; see [opencode.ai/docs](https://opencode.ai/docs/) for each primitive.

## Where the agent runs

The agent runtime is OpenCode, and **Kortix runs it in the cloud sandbox** — the sandbox agent server launches OpenCode with `OPENCODE_CONFIG_DIR` set to your `config_dir`. There is no Kortix command that runs the agent on your machine; the [CLI](/docs/reference/cli) is a cloud control plane, not a local runner.

Because `.kortix/opencode/` uses OpenCode's standard layout, the personas, skills, and tools are portable: install the upstream `opencode` binary and point its config dir at that folder and it reads the same files.

New files under `.kortix/opencode/` reach future sandbox sessions only after a [change request](/docs/reference/change-requests) merges them to `main`.