Projects

A project is one git repository with a manifest at its root — kortix.yaml by default. The repo is the project — files, history, agent config, and settings all live in git. No separate database to keep in sync.

Backed two ways:

• Kortix-managed repo — Kortix creates and hosts a private repo (default).
• Imported GitHub repo — link an existing repo; Kortix operates on it via the GitHub API.

When importing GitHub, choose the branch that becomes this project's default_branch (the repo's default is just the default choice). Each branch of the same GitHub repo can be a separate Kortix project with its own sessions and change requests, so main and dev can be managed as independent workspaces. The SDK exposes branch discovery through kortix.github.listRepositoryBranches and imports via kortix.github.linkRepository.

Either backing mode gives the project a default_branch that every session branches from and every change request merges into.

A project is a workspace, not your codebase

Treat a project as a standalone workspace — the home for your agent and everything it needs to act: its instructions, its connections to other tools, its automations, and its memory. It can also hold things worth keeping around — documents, notes, generated files. Keep it small; it's cloned into every session.

Your code lives elsewhere. When a task needs a codebase, the agent clones that repository on demand, does the work, and opens a pull request back to it. Large data and other systems are reached through connections, not copied in. The rule of thumb: if it's small and truly yours, keep it in the project; if it's large or lives somewhere else, reference it.

So you don't turn an existing codebase into a project by dropping a kortix.yaml into it — least of all a large monorepo, which would be cloned into every session. You create a dedicated project for the agent and point it at the repositories and tools it should work with.

What the control plane reads from the manifest

• project — name, description
• env — secret names
• sandbox + .kortix/Dockerfile — the sandbox image
• opencode.config_dir — agent config location (default .kortix/opencode)
• agents — agent governance (connectors/secrets/CLI/skills grants) and default_agent
• triggers — automations

Unknown keys are ignored. Dashboard edits to triggers/env are read-modify-writes on the same file, so in-session and dashboard edits round-trip.