Manifest reference

The manifest is the file the platform treats as authoritative for a project. This page lists every kortix.yaml (v2) key, its type, its default, and how the platform validates it. For the plain-language version, see Your project.

Two configuration surfaces

A Kortix project has two configuration surfaces with strict, non-overlapping ownership.

• Machine config — kortix.yaml at the repo root, plus any Dockerfile a sandbox template names. The platform reads this: the trigger sweep, the sandbox builder, session token minting, and the dashboard.
• Agent config — the agent files, skills, and harness files. The agent harness reads this, in the sandbox and locally.

Projects created before 2026-09 keep agents and skills under .kortix/opencode/ and memory under .kortix/memory/. Machine reads both layouts.

The join between the two halves is the agent's .md file. A manifest key agents.<name> governs the file that agents.<name>.file names, or agents/<name>.md when file is omitted. Every behavioral field lives only in that .md file's frontmatter and body, never in kortix.yaml:

• system prompt
• model, mode
• temperature, top_p
• steps, permission

The manifest's agents: block sets governance only: which agents may launch, and what each one may touch. The validator enforces this. It rejects a v2 agent block that contains any behavioral field, with an error that points at the agent's own .md file.

Location and versions

Any repo with a valid manifest at its root is a Kortix project. kortix.yaml (v2, YAML only) is the current format for new projects, created by the web "Create project" flow and by kortix init. kortix.toml (v1) still works for existing projects, but the platform accepts no new v2 features on it. See Legacy TOML for the v1 schema and the v1-to-v2 migration steps.

kortix_version: 2 requires YAML — a .toml file that declares kortix_version: 2 fails validation. A manifest that declares a version higher than 2 is rejected outright, so the platform never silently misreads a future field. Unknown top-level keys are ignored, so you can park your own metadata in the file.

validateManifest() is the single gate behind kortix ship, the change request merge check, and kortix validate. The same rules apply everywhere, so anything that merges into main is structurally sound. The schema is public and generated from the same package:

• kortix.v2.schema.json
• kortix.v1.schema.json
• kortix.schema.json (dispatches on kortix_version)

Point a kortix.yaml at the v2 schema for editor validation, or fetch it from the CLI:

# yaml-language-server: $schema=https://kortix.com/schema/kortix.v2.schema.json
kortix_version: 2

kortix schema --version 2

Full example

kortix_version: 2
default_agent: kortix

project:
  name: my-project
  description: What this project is.

env:
  required: [DATABASE_URL]
  optional: [STRIPE_API_KEY, WEBHOOK_SLACK_SECRET]

sandbox:
  templates:
    - slug: ml
      name: ML Development
      dockerfile: Dockerfile.ml
      cpu: 4
      memory: 16

opencode:
  config_dir: harnesses/opencode

agents:
  kortix:
    file: agents/kortix.md
    connectors: all
    secrets: all
    kortix_permissions: all
    skills: all

  release-bot:
    file: agents/release-bot.md
    sandbox: ml
    connectors: [github]
    kortix_permissions: [project.gitops.push]
    secrets: [GITHUB_AGENT_TOKEN]

triggers:
  - slug: daily-digest
    type: cron
    agent: kortix
    cron: '0 0 9 * * 1-5'
    timezone: America/Los_Angeles
    prompt: |
      Summarize yesterday's commits. Open a CR against main.

Top-level keys

imports:

Split one manifest across several YAML files. Use it when kortix.yaml outgrows one screen: 30 triggers with multi-line prompts, a connector per team, one file per agent group.

# kortix.yaml
kortix_version: 2
default_agent: kortix
imports:
  - triggers/                # a directory: every .yaml and .yml file below it
  - agents.yaml              # a single file
agents:
  kortix:
    connectors: all

kortix.yaml
agents.yaml
triggers/
  reports/
    weekly.yaml
    monthly.yaml
  dockets/
    freedom-forever.yaml

# triggers/reports/weekly.yaml
triggers:
  - slug: weekly-report
    name: Cross-Sector Weekly Report
    type: cron
    agent: galileo
    cron: "0 15 * * 0"
    prompt: |-
      Build the weekly report.

The platform reads the root file, resolves every import, and works on the merged document. Validation, trigger sweeps, agent grants, and connector sync all see one manifest. A trigger in one file can name an agent declared in another.

Rules

1. A path is relative to the repository root. .., absolute paths, and globs are rejected.
2. A directory import takes every .yaml and .yml file below it, at any depth, sorted by path. Other files are skipped.
3. An imported file declares triggers, connectors, agents, apps, and imports. Every other key (kortix_version, default_agent, runtime, project, env, opencode, sandbox, policy, policies) stays in the root file. An imported file that sets one fails validation.
4. An imported file can import more files. The limit is 8 levels and 200 files. A cycle is an error. A file reached twice merges once.
5. One name, one file. A trigger slug, connector slug, agent name, or app name declared in two files is an error that names both files. Nothing overrides silently.
6. Entries merge in order: the importing file first, then its imports in the order listed.

A broken import fails the whole manifest, the same way a YAML syntax error does. kortix validate, kortix ship, and the change request merge check all report it before it reaches main:

imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file

Edits go to the file that declares the entry. When the dashboard, the API, or kortix triggers enable|disable|rm changes a trigger, connector, agent, or app that an imported file declares, only that file is written. The root file is not rewritten. A new entry is written to the root file. Move it into an imported file by hand if you want it there.

imports requires kortix.yaml. A kortix.toml manifest ignores the key.

project:

Optional, human-facing metadata: name and description. The platform does not read this table for anything — a project's display name comes from its own database record. Treat it as documentation for people reading the repo.

env:

Declares the env var names your sessions need. Values live in the dashboard's Environment variables page, never inline in the manifest. The platform decrypts and injects them as plain env vars at session start.

env:
  required: [DATABASE_URL]
  optional: [STRIPE_API_KEY]

Env var names match ^[A-Z_][A-Z0-9_]*$. The Secrets Manager caps a name at 64 characters — a longer name parses here but can never get a value. Names starting with KORTIX_ can never get a value either. Keep names at 64 characters or fewer, and avoid the KORTIX_ prefix. Full contract: Secrets.

sandbox: and sandbox.templates

A list of named, bootable sandbox images. Optional — with no entries, every session boots the platform's default image. Each template needs exactly one of dockerfile (repo-relative) or image (a public Docker reference, tag- or digest-pinned).

sandbox:
  templates:
    - slug: ml
      name: ML Development
      dockerfile: Dockerfile.ml
      cpu: 4
      memory: 16
      disk: 50

Each value must be a positive integer. A value below the minimum fails validation with an error. A value above the maximum passes with a warning, then clamps at runtime. GPUs are not supported — declaring gpu produces a warning, not an error. See Runtime for what the runtime layer injects on top of your image.

sandbox.default

Set default on sandbox to make one template the project-wide default. Every session, trigger, and channel then boots it without naming a slug.

sandbox:
  default: dev
  templates:
    - slug: dev
      dockerfile: Dockerfile.dev

default must name a template declared in this manifest, or the reserved value "default" for the platform image.

An agent can select its environment with agents.<name>.sandbox. The value must name a manifest or dashboard template, or "default".

agents:
  researcher:
    sandbox: ml

Session template resolution uses this order:

1. Explicit session sandbox_slug.
2. Selected agent sandbox.
3. Project sandbox.default.
4. Platform "default".

Cron triggers, webhook triggers, schedules, and channels use the selected agent's template.

A spec change (cpu, memory, disk, container_runtime, or the image itself) rebuilds the project's snapshot. The new size applies on the next session, not a running one.

opencode:

Where the OpenCode config directory lives. Optional, with a default.

opencode:
  config_dir: harnesses/opencode

When config_dir is not set, Machine uses the first of harnesses/opencode and .kortix/opencode that holds an opencode.json or opencode.jsonc. That directory holds the files only OpenCode reads: opencode.jsonc, plugins/, tools/, and commands/. Agents and skills live at the repo root, in agents/ and skills/. opencode.jsonc stays the OpenCode-native registry for plugins, MCP servers, providers, and permissions — do not duplicate those settings in the manifest. See Agents.

triggers:

A list of cron, webhook, and monitor definitions. Each entry fires a session that runs prompt as its first message.

triggers:
  - slug: daily-digest
    type: cron
    cron: '0 0 9 * * 1-5'
    prompt: Summarize yesterday's commits.

Cron triggers need exactly one of cron (a 6-field expression) or run_at (a one-off ISO-8601 timestamp), plus timezone as an IANA name. Webhook triggers need secret_env, the name of a secret that uses broker delivery with the connector consumer. Monitor triggers need run (a repo-relative command) and mode (poll or stream), and reject every cron and webhook field. Full field reference, credential setup, payload templating, endpoints, and session strategy: see Triggers.

connectors:

A list of external tools an agent can call. The definition lives in git; credentials live in the platform, never in the manifest. See Connectors for the conceptual model.

connectors:
  - slug: gmail-read
    name: Gmail read only
    provider: pipedream
    app: gmail
    authorization_strategy: user
    policies:
      - match: search_email
        action: always_run

Provider-specific fields:

channel connectors rarely need a hand-written entry — connecting a channel from the dashboard creates one for you. See Slack & channels. The slugs kortix_slack, kortix_teams, kortix_email, and computer are platform-owned; using one with a different provider is a validation error. The computer connector is created when the first member connects a computer, because machine ids are account control-plane identities and must not enter the manifest.

connectors.auth: optional, for providers other than pipedream. type is bearer, basic, custom, api_key, oauth1, hmac, aws_sigv4, mtls, or none (default). oauth1 is restricted to openapi, postman, and http providers. in is header (default), query, or cookie. name is required when type is custom or api_key.

connectors.policies: a list of {match, action} pairs. match is a glob over tool names. action is always_run, require_approval, or block. Policies belong to the connector. Every connection under that connector uses the same policies.

policy.default_mode: a top-level key, separate from connectors:, that sets the project-wide connector approval mode. It takes allow_all (default; every unmatched tool runs) or risk (require approval for write and destructive unmatched calls). Set it with kortix connectors policy set --default <risk|allow_all> — see CLI.

Channels

v2 removes channels: from the schema. Channel-to-agent routing (Slack, Microsoft Teams, email, and voice today) is live operational state, not declarative config. You set it from the dashboard's Channels page or from chat commands, the same boundary that keeps credentials out of git. Connecting a channel still creates a connectors entry with provider: channel for the agent to call. See Slack & channels. The v1 [[channels]] table is covered in Legacy TOML.

agents:

A name-to-block map, keyed by agent name. This map is governance only — it grants what an agent may touch, never what it says or does.

This block is the second of the two bindings: a principal gets roles from Kortix, and an agent additionally carries the Kortix permissions declared here. A session can only do what both allow. See One vocabulary, two bindings.

default_agent: kortix

agents:
  kortix:
    file: agents/kortix.md
    connectors: all
    secrets: all
    kortix_permissions: all
    skills: all

  release-bot:
    file: agents/release-bot.md
    connectors: [github]
    connectors_required: [github]
    kortix_permissions: [project.gitops.push]
    secrets: [GITHUB_AGENT_TOKEN]

v2 is deny-by-default: an omitted connectors, secrets, kortix_permissions, skills, or apps on a declared agent resolves to none. Grant every permission an agent needs explicitly, as the starter's kortix agent does above. A project migrating from v1 must re-grant everything by hand — v1 defaults env (secrets) to all when omitted, the opposite of v2.

connectors_personal remains a deprecated input alias for connectors_required. New manifests must use connectors_required. The connector's authorization_strategy decides whether the authorization is project-owned or member-owned.

kortix_permissions grants come from a fixed set of project-scoped permissions (project.read, project.gitops.push, project.gitops.merge, project.gitops.ref.any, project.trigger.*, project.secret.*, project.connector.*, and more). Account-scoped permissions — member.*, billing.*, project.create — can never be granted to an agent. Run kortix validate --scopes from inside a session to print the live, grantable list.

The agent file

agents.<name>.file names the agent's .md, relative to the repo root.

agents:
  support:
    file: agents/support.md

• The path must end in .md.
• The path must not start with / or -. It must not contain a . or .. segment, or an empty segment.
• Each segment uses only letters, digits, _, -, ., and spaces.
• When file is omitted, Machine reads agents/<name>.md, then .kortix/opencode/agents/<name>.md. With opencode.config_dir set, the second path is <config_dir>/agents/<name>.md.
• When the dashboard saves an agent that has a .md, it writes file with that path.
• The API refuses a request that changes file (400, code invalid_config). To move an agent, move its .md and update file in kortix.yaml in the same commit.

kortix validate and the change request merge check reject an invalid file with an error on agents.<name>.file.

When config changes take effect

• A manifest, agents/, skills/, or OpenCode config directory edit applies only after a change request merges to main. Sessions and the trigger sweep read the default branch, not session branches.
• A trigger's cron or webhook change is picked up by the scheduler within seconds of the merge.
• A sandbox image or hardware change rebuilds the snapshot. The new spec applies on the next session, not the current one.
• A secret value change in the dashboard resolves at sandbox-create time. It applies on the next session, not a running one.

Round-trip rules

Dashboard edits are a read-modify-write on the file that declares the entry: kortix.yaml, or an imported file. To keep diffs clean across UI and in-session edits:

1. Keep kortix_version as the first key.
2. Inside a trigger entry, order fields slug, name, type, agent, enabled, then type-specific fields, then prompt last.
3. If you add a webhook trigger before its secret is set, list the secret name in env.optional. Leave the trigger enabled: false until the value is in.

Repository access

Set agents.<name>.repository_access to false for agents that do not need project source files. They can still create sandbox files and use their granted tools, secrets, and connectors. Set it to true for agents that need the repository. Git permissions remain separate. Change this setting in the agent editor under Workspace → Project repository access. The setting applies to new sessions. Existing sessions keep their saved policy, including after runtime replacement.

agents:
  support:
    repository_access: false
  engineer:
    repository_access: true

The deprecated workspace field remains readable: branch means true, and runtime means false. Legacy read configurations still reject session creation until you replace the field with an explicit boolean. There is no read-only repository mode. Conflicting old and new fields are rejected. The editor and SDK send repository_access. For disabled access, the API also stores workspace: runtime as a compatibility mirror. This preserves the restriction for older API replicas during rollout or rollback. API reads omit the mirror. Hand-authored manifests using only repository_access require the updated API.