Projects

A project is one git repository that holds your agents, skills, tools, memory and kortix.yaml: its layout, how a change takes effect, its settings, feature flags and deletion.

A project is one git repository with kortix.yaml at its root. It holds your agents, skills, tools, memory, triggers and connector declarations as files. This page is for the people who set up a project and keep it running.

What a project is

• One repository, one default branch. Every session starts on its own branch from the default branch. Every change request merges back into it. A session reads config from its base branch: the default branch unless the session was created with another base_ref. Triggers read the default branch.
• Config is files. Agents, skills, tools and memory are files in the repository. You change them with a commit, not in a separate config store. Secret values, feature flags and reminders live on the platform, not in git.
• Managed, GitHub or any other git host. All three work the same once the project exists. See Your project’s repository.

Each branch of a GitHub repository can be its own project. main and dev can run as two projects, each with its own sessions and change requests.

A project is not your codebase. Every session clones the project, so keep it small. When a task needs a codebase, the agent clones that repository in the session, does the work, and opens a change request there. Do not add kortix.yaml to an existing codebase. Create a dedicated project and point its agents at the repositories they work on.

To create a project, follow the Quickstart.

Repository layout

• A kortix_version: 3 project reads no harness folder. Its slash commands are declared in kortix.yaml; see commands (v3).
• agents.<name>.file, opencode.config_dir and pi.config_dir in kortix.yaml move an agent file or a harness folder to another path.
• The manifest path is a project setting, kortix.yaml by default. See File and schema.
• A project that keeps agents and skills under .kortix/opencode/ and memory under .kortix/memory/ works unchanged. Every reader accepts both layouts.
• To remove a project skill, open its card under Customize → Skills and select Remove, or run kortix marketplace uninstall skills/<name> --yes. One commit on the default branch deletes the folder with every file in it and takes the skill off every agent’s skills list. The platform kortix-* skills have no Remove.

What a new project contains

A new project starts from the general starter. It commits these files to the default branch:

Kortix adds 12 managed kortix-* skills to every session when it boots, kortix-cli among them. They overwrite a committed copy with the same name. See Agents & permissions. Read one with kortix system-skills get <name>.

To turn on the reflection loop, change enabled: false to enabled: true on the harness-reflector trigger in kortix.yaml and merge the change. Keep its prompt: unchanged. Each run starts a session in its own sandbox.

Create a project with kortix init

kortix init my-agent && cd my-agent

kortix init [project-name] creates a new directory from the general starter. It writes kortix.yaml, agents/, skills/, memory/ and harnesses/opencode/, runs git init -b main, and asks which local coding tools to wire. It refuses a directory that exists and is not empty.

kortix init does not create the cloud project and does not write .kortix/link.json. The first kortix ship does both. See The first ship. The local tool wiring never changes how sessions run in the cloud.

Memory

memory/ holds what the project knows about itself: its purpose, connections, conventions and decisions. memory/MEMORY.md is the index, with one line per file.

• Read. Kortix does not put memory into the prompt. The managed kortix-memory skill tells an agent to read MEMORY.md at the start of a task, then the files the index points to.
• Write. The memory tool (memory: kortix:memory under tools:) views, creates, edits, inserts into, renames and deletes files under memory/ only. Without that line, agents edit the files with their file tools.
• Persist. A memory edit is an ordinary file change on the session branch. Other sessions see it only after a change request merges it into the default branch.
• Curate. harness-reflector cleans up memory on each run when its trigger is on.

Do not write secrets or personal data into memory. Store credentials as secrets.

Install from the marketplace

The marketplace lists skills and agents you can add to a project. Browse it at kortix.com/marketplace or from the CLI:

kortix marketplace search pdf                 # search by text
kortix marketplace list --type skill          # filter by type; --source kortix filters by source
kortix marketplace show <id|name>             # one item
kortix marketplace install <id|name>          # import into the linked project

install starts a session in the project. Its agent reads the item, adds what fits, and opens a change request. The install never merges: you review and merge the change request. --project <id> picks another project. --timeout <seconds> sets the deadline (default 300).

The marketplace feature flag gates install. It is on by default. With the flag off, install answers 403 feature_disabled. search, list and show keep working.

How a change takes effect

To force a running session onto the newest config, run kortix sessions reload <session_id>. It restarts the agent runtime and refuses during a turn unless you pass --force. Config comes from the base branch explains releases and fallback.

Project settings

Open Customize → Settings in a project. The sections:

The same settings from the CLI:

kortix projects info                         # the linked or default project (--json)
kortix projects set --name "My project"
kortix projects set --branch main            # default branch
kortix projects set --manifest kortix.yaml   # manifest path

A project on kortix.toml migrates with Upgrades or kortix projects upgrade. See Migrate from kortix.toml.

kortix projects set needs project.settings.write. It writes only the fields you pass. --project <id> acts on another project. Which project a command uses explains the default.

Feature flags

A feature flag turns one surface on or off for one project. Kortix stores the flag on the project, never in kortix.yaml. A flag does not travel with a clone or a fork, and it changes nothing in other projects.

Turn a flag on or off

• Web: Customize → Settings → Feature flags. Each row shows its origin: Default on, Default off, Overridden for this project or Managed by Kortix.

• CLI:

  kortix projects features                     # every flag: state (on, off, n/a) and origin (default, override, kortix, unavailable)
  kortix projects features enable reminders
  kortix projects features disable reminders
  kortix projects features reset reminders     # clear the override; follow the default

  Add --project <id> for another project and --json for machine output.

• API: PATCH /v1/projects/<project_id>/features with {"feature": "reminders", "enabled": true}. false turns it off. null clears the override.

• SDK: kortix.project(projectId).updateFeatureFlag('reminders', true). useFeatureFlag(projectId, key) from @kortix/sdk/react reads the effective state. See React.

A write needs project.settings.write. An unknown key answers 400 Unknown feature flag '<key>'.

A flag the deployment does not support is unavailable. It stays off whatever the project sets. Settings hides it, and the CLI prints state n/a with origin unavailable.

A toggle of these flags also updates running state. The API response does not wait for it.

• agentmail_email: the email channel connector appears or goes.
• event_triggers: app-event subscriptions start or stop.
• connectors_v2: the Telegram channel connector appears or goes. With event_triggers on, the app events that Kortix checks start, or move to error and stop.
• genui: warm sandboxes from before the toggle are not used for new sessions.

Every flag

When a flag is off

A route behind an off flag answers 403:

{
  "error": "Reminders is not enabled for this project. Enable it in Settings → Feature flags.",
  "code": "feature_disabled",
  "feature": "reminders"
}

Branch on code, never on error. The SDK exports isFeatureDisabledError(error) and featureDisabledKey(error). The error text has three forms:

• volumes is an ordinary project flag. It is listed only on a deployment with Platinum.
• drives follows the project’s volumes flag. It is never listed. A write answers 400. With Volumes off, every Files write answers 403 feature_disabled, and a file a session already wrote under /drives still opens.

Delete a project

1. Open Customize → Settings → General.
2. Under Danger zone, select Delete workspace and confirm.

From the CLI, run kortix projects rm [<project_id>]. It acts on the linked project when you pass no id. -y skips the confirmation. Both need project.delete. A delete cannot be undone.

Kortix deletes a managed repository with the project. A repository you connected yourself is left untouched.