How Kortix works

A project is one git repository with a manifest — kortix.yaml by default, or legacy kortix.toml — at its root. A session runs the agent in an isolated sandbox VM with the repo cloned onto a branch named after the session. The sandbox is disposable; the branch persists. Work reaches the default branch only via a merged change request.

The pieces

• Projects — a git repo (Kortix-managed or imported GitHub, pinned to one branch) plus its manifest.
• Sessions — isolated sandbox VMs, each on its own branch. Many run at once without interfering.
• Agents — OpenCode, governed by the manifest's agents: map and implemented through .kortix/opencode/.
• Change requests — the git merge layer that lands a branch on the default branch.
• Secrets — per-project encrypted values, given to sessions as environment variables.
• Triggers — spawn a session on a schedule or from a webhook.
• Connections — let the agent call external tools, brokered server-side.
• Channels — drive a project from Slack.
• Accounts — who owns projects and who can access them.

When a session starts

1. The control plane (the Kortix API) inserts the session (provisioning) and cuts a branch from the default branch, named after the session id.
2. It resolves a content-addressed snapshot — the platform's default image (or your own Dockerfile, if the manifest declares a sandbox.templates entry for it) plus the Kortix runtime layer, built by the configured sandbox provider. Unchanged projects reuse the cached image.
3. The sandbox provider boots the VM. The kortix-agent daemon clones the repo to /workspace, fetches git credentials just-in-time, and launches OpenCode. Status → running.
4. The agent works with secrets as env vars, committing and pushing to the session branch.
5. It opens a change request; you review and merge — the only path to the default branch.

Two config surfaces

The manifest (kortix.yaml) + .kortix/Dockerfile are Kortix-owned; .kortix/opencode/ is OpenCode-native runtime behavior. agents: is a name-keyed map that is governance only — connectors, secrets, kortix_cli, skills, which agent names are launchable, and what each may touch. Everything about how an agent behaves (prompt, mode, tools, permissions) lives in that agent's own .kortix/opencode/agents/<name>.md, a stock OpenCode agent file. default_agent is required and must name a declared, enabled agent. See Kortix vs OpenCode config. Drive any of it from a terminal with the CLI — it controls the cloud, it doesn't run the agent locally.