# Projects

A project is one git repository plus a kortix.yaml manifest.

Canonical page: https://kortix.com/docs/concepts/projects

A **project is one git repository** with a [manifest](/docs/reference/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.

> **kortix.yaml vs legacy kortix.toml**
> New projects get `kortix.yaml` (`kortix_version: 2`) from the starter template.
> Existing projects may still run `kortix.toml` (`kortix_version: 1`) — the
> platform reads both indefinitely. Migrate in-app via the Customize panel's
> **Upgrades** section — run **Migrate manifest to v2 (kortix.yaml)**.
> Full field-by-field comparison: [manifest reference](/docs/reference/manifest).

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](/docs/concepts/sessions) branches from and every
[change request](/docs/concepts/change-requests) 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](/docs/concepts/connections) to other tools, its
[automations](/docs/concepts/triggers), 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](/docs/concepts/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](/docs/reference/secrets) names
- `sandbox` + `.kortix/Dockerfile` — the [sandbox image](/docs/reference/sandbox-image)
- `opencode.config_dir` — agent config location (default `.kortix/opencode`)
- `agents` — [agent](/docs/concepts/agents) governance (connectors/secrets/CLI/skills grants) and `default_agent`
- `triggers` — [automations](/docs/concepts/triggers)

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.

> **v1 equivalents**
> In legacy `kortix.toml` (`kortix_version: 1`) these are TOML tables:
> `[project]`, `[env]`, `[[sandbox.templates]]`, `[opencode]`, `[[agents]]` (array,
> grant field named `env` instead of `secrets`), `[[triggers]]`. v1 also
> has `[[channels]]`, removed outright in v2 — channel↔agent routing is dashboard/CLI
> managed, never committed.