Legacy kortix.toml
Support status and the migration path from v1 kortix.toml to v2 kortix.yaml.
This page covers the v1 manifest (kortix.toml, kortix_version: 1). For the current manifest, see Manifest reference.
Support status
Kortix still supports v1 manifests. The platform resolves a project's manifest in this order: kortix.yaml, then kortix.yml, then kortix.toml. The current starter creates one v2 kortix.yaml. A v1 project keeps working with no forced upgrade.
v1 accepts TOML or YAML syntax. Version 2 accepts YAML only. A v2 manifest written in TOML fails validation.
Migrate to v2
Create kortix.yaml at the repo root. Set kortix_version: 2.
Convert [[agents]] to an agents: map, keyed by agent name.
Rename each agent's env field to secrets. List every secret the agent needs — v2 does not grant secrets by default.
Add default_agent, naming the agent that runs by default.
Delete [[channels]]. Reconnect each channel from the dashboard.
If you use [sandbox] or [[sandboxes]], move each image definition under sandbox.templates.
Run kortix validate against kortix.yaml. Fix any error it reports.
Delete kortix.toml.
Agent behavior — system prompt, model, mode, temperature, and more — does not change. It lives in each agent's .md frontmatter. A v1 project keeps those files under .kortix/opencode/agents/, and v2 still reads them there. v2 projects created from 2026-09 keep them in agents/ at the repo root, and agents.<name>.file names each one. See Agents.
Check the result with kortix validate --file kortix.yaml. Fetch the full v2 schema with kortix schema --version 2. See CLI reference for both commands.
Key differences
v1 (kortix_version: 1) | v2 (kortix_version: 2) | Change |
|---|---|---|
[[agents]] (array) | agents: (map keyed by name) | Convert each array item to a map entry. |
[[agents]].env | agents.<name>.secrets | Renamed. Default flips from all to none — see the callout below. |
[[agents]].model | removed | Dead in v1 (parsed, never applied). Agent behavior always comes from the agent's .md frontmatter. |
[[agents]].file | agents.<name>.file | Dead in v1 (parsed, never applied). In v2 it names the agent's .md. |
no default_agent | default_agent (required) | Must name a declared, enabled agent. |
[[channels]] | removed | Channel routing is dashboard-managed. A connected channel appears as a connectors: entry with provider: channel. |
[sandbox] (singular, image keys directly on it) | sandbox.templates (list) | Move each image into a template entry. |
[[sandboxes]] | sandbox.templates | Renamed. |
:::warning[Secrets default to none in v2]
In v1, an agent with no env field gets every project secret by default. In v2, an agent with no secrets field gets none. When you migrate, list every secret each agent needs — an agent that silently loses a secret can fail mid-task.
:::
A few kortix_permissions actions are legacy-tolerated in v1 (project.session.exec, project.gateway.routing.edit, project.schedule.read, project.schedule.write, project.webhook.read, project.webhook.write, channel.read, channel.connect, channel.send, channel.disconnect) — the platform warns but allows them. The same actions are a hard error in v2. Remove them from any agent's kortix_permissions grant before you migrate.