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.

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.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
• apps — deployable apps (experimental)

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