Kortix vs OpenCode config
The strict ownership boundary between the manifest and the .kortix/opencode/ config directory.
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, apps, and which agents the platform may launch/authorize. - OpenCode owns
.kortix/opencode/— how the runtime behaves.opencode.jsoncremains 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 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 |
| Apps (experimental) | kortix.yaml apps: | 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, what gets deployed, 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. The .kortix/opencode/ directory follows OpenCode's standard layout; see 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 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 merges them to main.