Manifest reference

The one file the platform treats as authoritative for a project. For the plain-language version, see Projects.

The manifest lives at the repo root — kortix.yaml (v2, the current default for new projects), its kortix.yml short-extension sibling, or kortix.toml (v1, legacy, still fully supported for existing projects). Any repo with a valid manifest at the root is a Kortix project. When more than one candidate file is present, the platform resolves them in priority order — .yaml first, then .yml, then .toml — and reads the first one it finds. The parser is permissive — it never throws on a bad entry: bad triggers and apps go into an errors list alongside the good ones, and unknown top-level keys are ignored (park your own metadata freely).

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

Full example (v2, kortix.yaml)

# yaml-language-server: $schema=https://kortix.com/schema/kortix.v2.schema.json
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: .kortix/Dockerfile.ml   # repo-relative; or `image: python:3.12-slim`
      cpu: 4
      memory: 16

opencode:
  config_dir: .kortix/opencode

agents:
  kortix:                    # governance ONLY — behavior lives in .kortix/opencode/agents/kortix.md
    connectors: all
    secrets: all
    kortix_cli: all
    skills: all

  release-bot:                # a scoped specialist
    connectors: [github]
    kortix_cli: [project.cr.open]   # may open a CR, but not merge it
    secrets: [GITHUB_AGENT_TOKEN]   # only this secret, not every project secret

triggers:
  - slug: daily-digest
    name: Daily digest
    type: cron
    agent: kortix
    enabled: true
    cron: "0 0 9 * * 1-5"          # 09:00 Mon–Fri
    timezone: America/Los_Angeles
    prompt: |
      Summarize yesterday's commits across the repo. Save the result to
      notes/digest-{{ fired_at }}.md and open a CR against main.

  - slug: slack-hook
    name: Slack handler
    type: webhook
    agent: kortix
    enabled: true
    secret_env: WEBHOOK_SLACK_SECRET   # add value via Secrets Manager
    prompt: |
      Slack event from {{ headers.user_agent }}.
      User said: {{ body.text }}

agents: is a governance-only map — see agents: below. There's no [[channels]] in v2 (see Channels).

Legacy example (v1, kortix.toml)

# Pinned schema version. Lets the platform evolve safely.
kortix_version = 1

[project]
name = "my-project"
description = "What this project is."

[env]
required = ["DATABASE_URL"]
optional = ["STRIPE_API_KEY", "WEBHOOK_SLACK_SECRET"]

[[sandbox.templates]]
slug = "ml"                         # unique per project
name = "ML Development"
dockerfile = ".kortix/Dockerfile.ml"   # repo-relative; or `image = "python:3.12-slim"`
cpu = 4
memory = 16

[opencode]
config_dir = ".kortix/opencode"

[[triggers]]
slug = "daily-digest"
name = "Daily digest"
type = "cron"
agent = "kortix"
enabled = true
cron = "0 0 9 * * 1-5"            # 09:00 Mon–Fri
timezone = "America/Los_Angeles"
prompt = """
Summarize yesterday's commits across the repo. Save the result to
notes/digest-{{ cron.fired_at }}.md and open a CR against main.
"""

[[triggers]]
slug = "slack-hook"
name = "Slack handler"
type = "webhook"
agent = "kortix"
enabled = true
secret_env = "WEBHOOK_SLACK_SECRET"   # add value via Secrets Manager
prompt = """
Slack event from {{ headers.user_agent }}.
User said: {{ body.text }}
"""

Schema version

kortix_version: 2

kortix_version is the required schema version. A manifest declaring a version higher than the platform knows about is rejected outright — the platform won't silently misread future fields. kortix_version: 2 requires YAML (.yaml); a .toml file declaring kortix_version: 2 is a validation error pointing at the migration flow. When the platform writes the manifest back after a dashboard edit, it ensures kortix_version is the first key.

runtime: (v2 only)

Optional top-level string, v2 only. Today the only legal value is opencode — the default when omitted — reserved so a future runtime (e.g. a hypothetical runtime: claude) is a one-line manifest change rather than a schema break. It has no other effect yet.

runtime: opencode

What's parsed where

project: / [project]

Optional, human-facing metadata (name, description). The platform does not currently read this table — a project's display name comes from its own record, not the manifest — so treat it as a convention for people reading the repo.

env: / [env]

Declares the env var names your sessions need — same key in both versions. Values live in the dashboard's Environment variables page (still project_secrets/secrets under the hood), never inline; the platform decrypts and injects them as plain env vars at session start. (The per-agent grant field is what's renamed in v2 — env → secrets inside each agents: block — see agents: below.)

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

Manifest name validation is permissive — items match ^[A-Z_][A-Z0-9_]*$ (no length cap). The Secrets Manager API caps names at 64 chars (^[A-Z_][A-Z0-9_]{0,63}$), so a longer name is accepted in the manifest but can never get a value. Keep names ≤ 64 chars.

The KORTIX_* prefix is reserved at the Secrets Manager surface, not at parse time: listing KORTIX_FOO in [env] parses fine but can never have a value. Don't. Full contract: Secrets.

sandbox.templates / [[sandbox.templates]]

A list of named, bootable sandbox images; the Kortix runtime layer (opencode CLI, agent daemon, entrypoint) is layered on top of it automatically. Optional — with no entries, every session boots the always-available platform default image. Declare as many templates as you like; a session picks one by slug. This is also where you size the sandbox hardware.

The schema mirrors the runtime provider (Daytona): an image comes either from a Dockerfile in your repo or a public Docker image reference, and the resource spec maps onto the provider's cpu / memory / disk.

sandbox:
  templates:
    # From a repo Dockerfile
    - slug: ml                          # unique per project; not "default" (reserved)
      name: ML Development              # optional display label
      dockerfile: .kortix/Dockerfile.ml  # repo-relative
      cpu: 4                            # vCPU cores
      memory: 16                        # GiB
      disk: 50                          # GiB

    # From a public image
    - slug: python
      name: Python 3.12
      image: python:3.12-slim           # must be tag- or digest-pinned
      cpu: 2
      memory: 4

[[sandbox.templates]]
slug       = "ml"
name       = "ML Development"
dockerfile = ".kortix/Dockerfile.ml"
cpu        = 4
memory     = 16
disk       = 50

[[sandbox.templates]]
slug  = "python"
name  = "Python 3.12"
image = "python:3.12-slim"
cpu   = 2
memory = 4

Exactly one of image or dockerfile is required per entry. A Dockerfile path must be repo-relative — absolute paths and .. traversal are rejected. GPUs are not supported in this version. See Sandbox image for what the runtime layer injects and what your Dockerfile can do.

sandbox.default — the project-wide default template

By default every session boots the platform default image; a session opts into a template by passing its slug. Set default on sandbox to make one of your templates the project-wide default instead — then every session (the dashboard's "new session", triggers, channels) boots it without specifying a slug.

sandbox:
  default: dev          # or "default" for the platform image (the implicit default)
  templates:
    - slug: dev
      dockerfile: .kortix/Dockerfile

default must name a template defined in this manifest (or the reserved "default"). It's the only key allowed alongside templates — image/build keys directly on sandbox are the removed legacy singular shape and are rejected.

Hardware spec

cpu / memory / disk size the sandbox. Each is independent and optional — leave one out and the runtime provider's default applies. Values are coerced to whole numbers; a value below 1 falls back to the default, and a value above the platform ceiling (cpu 32, memory 128 GiB, disk 500 GiB) is clamped down rather than rejected.

opencode: / [opencode]

Where OpenCode's config dir lives. Optional, with a default. The agent daemon launches opencode with OPENCODE_CONFIG_DIR pointed here.

opencode:
  config_dir: .kortix/opencode

That directory holds agents, skills, slash commands, tools, plugins, and opencode.jsonc — the layout opencode reads by convention. OpenCode owns the runtime semantics; Kortix may inspect metadata to build server-side agent/model UI surfaces. See Kortix vs OpenCode config and opencode.ai/docs.

opencode.jsonc remains the OpenCode-native registry for plugins, MCP servers, providers, model/provider settings, permissions, and default runtime behavior. Do not duplicate those details in the manifest. Use agents: (v2) / [[agents]] (v1) for the Kortix-side decision of which agents are launchable and what server-side grants they receive — in v2, EVERY behavioral field (model, mode, tools, permission, the prompt itself) lives in the agent's own .md frontmatter instead, never in the manifest.

Legacy v1 projects with no [[agents]] keep OpenCode-native discovery for backward compatibility. Projects on agents: (v2) or [[agents]] (v1) opt into declarative, server-side agent discovery: product UI should use the API's registered agents, while unregistered OpenCode files may still exist for local experiments or runtime internals. Model pickers should similarly come from the server / LLM-gateway catalog rather than a sandbox-local OpenCode provider list.

triggers: / [[triggers]]

Each entry fires a session that runs prompt as its initial message — a fresh session by default, or the trigger's prior session when session_mode: reuse (see below). Sorted alphabetically by slug in the parsed output, so UI ordering is stable. Full reference: Triggers.

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

Common fields

Cron-only: cron (6-field croner second minute hour day month weekday) or a one-off run_at (camelCase runAt, an ISO-8601 datetime, e.g. 2026-06-01T09:00:00Z) — exactly one of the two is required; run_at fires the trigger once at that instant instead of on a recurring schedule. timezone (IANA name, default "UTC") applies to cron. Webhook-only: secret_env (name of a project_secrets entry holding the HMAC secret).

The parser accepts only canonical trigger field names. Slug uniqueness is per-section — a trigger and an app may share a slug; two triggers may not.

Channels — removed in v2

v2 removes channels: from the schema outright. Channel↔agent routing (Slack today; Teams/Discord/etc. later) is live operational state — the dashboard's Channels page or Slack's own slash commands — not declarative config, the same boundary rule that keeps credentials out of git. The channel integration itself still shows up as a connectors entry with provider: channel once you connect one; only the routing table moved out of the manifest.

[[channels]] (v1, legacy)

Array of tables. Each entry documents a chat platform (Slack today) connected to the project. Validated but not wired to any runtime behavior — declaring one, or editing enabled/agent/events/prompt_prefix, changes nothing about how the platform actually routes messages. The live channel→agent binding is the chat_channel_bindings database row, set from inside Slack (its slash commands) or the dashboard's Channels page, not from this file.

[[channels]]
platform = "slack"
enabled = true                  # optional, default true
agent = "kortix"                 # optional — parsed, not consumed
events = ["mention", "dm"]        # optional, array of strings — parsed, not consumed
prompt_prefix = """
You're working on {{ project.name }}.
{{ message.text }}
"""

connectors: / [[connectors]]

Each entry connects an external tool the agent can call. The definition lives in git; credentials live in the platform, never here. Full model: Connections.

connectors:
  - slug: gmail-work
    provider: pipedream     # pipedream | mcp | openapi | graphql | http | channel
    app: gmail               # pipedream app slug
    credential: shared        # shared is the only mode — see below
    policies:
      - match: "*"
        action: require_approval  # always_run | require_approval | block

Provider-specific fields:

• pipedream — app (required), account (optional, defaults to slug).
• mcp — url (required), transport = http (default) or sse.
• openapi — spec (required: URL or repo-relative path).
• graphql — endpoint (required), spec (optional SDL).
• http — base_url (required), spec (optional).
• channel — platform (required) = slack | email | meet. Chat platforms. You rarely declare these by hand — connecting one (Channels) auto-materializes the connector (credential = the install token, resolved server-side), so the agent can call it through the Executor and you manage it in Connectors.
• computer — connected machines over the Agent Computer Tunnel. Synth-only: you cannot declare it by hand. Connecting a machine (Computers) auto-materializes a single computer connector that fronts all your machines (it has no credential — the live tunnel is the credential; per-machine access is granted in Computers).

Reserved slugs: kortix_slack, kortix_email, kortix_meet (each locked to provider: channel) and computer (locked to provider: computer) are platform-owned — declaring one of these slugs with any other provider is a validation error, the same rule that keeps computer synth-only above.

connectors.auth

Optional. type = bearer | basic | custom | none (default none); in = header (default) or query; name (required when type = "custom"); prefix (optional). The credential value is stored in the platform connector credential store, not in the manifest. Auth is not allowed with provider: pipedream.

connectors.policies / [[connectors.policies]]

Optional per-tool gates. match (glob over tool names, required) + action = always_run | require_approval | block (required).

agents: (v2)

A name→block map, keyed by agent name — governance only. There is no model/mode/description/permission/prompt here at all: every behavioral field lives in that agent's own OpenCode .md file under .kortix/opencode/agents/<name>.md (frontmatter + body, a stock OpenCode agent file — no Kortix-specific split). The map key is the join to that .md's filename. default_agent (top-level, required in v2) must name a declared, enabled agent here.

default_agent: kortix

agents:
  kortix:                    # the default general-purpose agent
    connectors: all           # every connector profile
    secrets: all               # every project secret
    kortix_cli: all             # full Kortix CLI/API powers (∩ the launching user's role)
    skills: all

  release-bot:                 # a scoped specialist
    connectors: [github]
    kortix_cli: [project.cr.open]   # may open a CR, but not merge it
    secrets: [GITHUB_AGENT_TOKEN]    # only this secret, not every project secret

v2 is deny-by-default: an omitted connectors/secrets/kortix_cli/skills on a declared agent resolves to none, the opposite of v1's per-field defaults. Give an agent every grant explicitly (as the starter's kortix agent does above) if it should keep full access.

[[agents]] (v1, legacy)

Array of tables. Optional — with no [[agents]] section, every session is capped only by the launching human's role (the project hasn't adopted per-agent governance). Adding any [[agents]] entry opts the whole project into declarative, server-side agent governance: any agent name not listed here is then default-denied — it still runs its OpenCode .md behavior, but with no connectors, no kortix_cli powers, and no project secrets.

An agent's behavior (prompt, mode, tools, permission tree) still lives entirely in its OpenCode .md file under .kortix/opencode/agents/. [[agents]] is a governance overlay on top of that: which agent names the platform will launch, and what each one may touch.

[[agents]]
name       = "kortix"            # your default general-purpose agent
kortix_cli = "all"                # full Kortix CLI/API powers (∩ the launching user's role)
connectors = "all"                # every connector profile

[[agents]]
name       = "release-bot"       # a scoped specialist
connectors = ["github"]
kortix_cli = ["project.cr.open"]  # may open a CR, but not merge it
env        = ["GITHUB_AGENT_TOKEN"]  # only this secret, instead of every project secret

apps: / [[apps]] (experimental)

Gated per project, not by a single global switch. Apps is one entry in the platform's experimental-feature registry: each project has an explicit choice — on or off — toggled from Customize → Settings, stored in projects.metadata (never in the manifest). KORTIX_APPS_EXPERIMENTAL is only the operator-wide default applied when a project hasn't made an explicit choice; a project can enable Apps even when that env var is false, and can opt out even when it's true. With the effective gate off for a project, its /apps routes return 404 (JSON error pointing at Customize → Settings) and the deploy sweep skips it — entries are parsed but never acted on; the sweep evaluates every active project individually rather than skipping the whole fleet when the operator default is off. Each entry declares a deployable surface alongside the agent, fly.toml-style. The platform dispatches through a provider adapter (Freestyle today; pluggable) and records each deploy in the deployments table.

apps:
  - slug: marketing-site
    name: Marketing site
    enabled: true
    framework: next
    # domains: [marketing.example.com]   # optional — omit for a free *.style.dev URL
    source:
      type: git            # or "tar"
      repo: https://github.com/me/site
      branch: main
      root_path: apps/site
    build:
      command: pnpm build
      out_dir: dist
    env:
      NEXT_PUBLIC_API_URL: https://api.example.com

Entries sort alphabetically by slug; slug uniqueness is per-section.

[apps.source]

[apps.build]

If both are empty, the parsed entry collapses to null — the provider treats it as "no build phase."

[apps.env]

Key/value map. Keys must match ^[A-Za-z_][A-Za-z0-9_]*$ (mixed case allowed, unlike [env] secrets which are uppercase-only). Values must be strings — numbers and booleans are rejected.

Hash-based redeploy

Apps redeploy when the manifest-derived hash of their config changes. The hash excludes slug and name, so renaming an app doesn't trigger a redeploy. Edits to source, build, env, domains, framework, or enabled do.

Round-trip rules

Dashboard manifest edits are a read-modify-write on the same file. To keep the diff clean across UI and in-session edits:

• Keep kortix_version as the first key.
• Inside a trigger entry (triggers: in v2, [[triggers]] in v1), write fields in this order: slug, name, type, agent, enabled, then type-specific fields, then prompt last.
• If you add a webhook trigger before its secret is set, declare the secret name in env.optional so it shows up in the dashboard's Environment variables page, and leave the trigger enabled: false until the value is in.