How Kortix works

A project is one git repository with a 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) plus its manifest.
• Sessions — isolated Daytona sandbox VMs, each on its own branch. Many run at once without interfering.
• Agents — OpenCode, configured from .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 — your .kortix/Dockerfile plus the Kortix runtime layer, built on Daytona. Unchanged projects reuse the cached image.
3. Daytona 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

kortix.toml + .kortix/Dockerfile are Kortix-owned; .kortix/opencode/ is agent behavior, read only by OpenCode. 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.