Projects

A project is one git repository with a kortix.toml at its root. 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.

Either way the project has 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.toml 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 kortix.toml

• [project] — name, description
• [env] — secret names
• [sandbox] + .kortix/Dockerfile — the sandbox image
• [opencode] config_dir — agent config location (default .kortix/opencode)
• [[triggers]] — automations
• [[apps]] — deployable apps (experimental)

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