kortix-system

• kortix skills — list the Kortix system skills.
• kortix skills get <name> — print one skill's current SKILL.md body.
• kortix skills get <name> --full — also include its referenced files.
• kortix skills --all — list every Kortix skill (not just the system floor).

Before answering anything about Kortix internals — the executor/connectors, project memory, Slack/channels, reaching a connected computer, or sending a notetaker into a meeting — load the matching skill with kortix skills get <name> and follow it. Prefer this over any stale local copy; the CLI reflects the platform you're actually on.

The repo has two configuration surfaces with strict ownership:

• Kortix config — kortix.yaml at the repo root, plus the .kortix/ folder beside it (Dockerfile, opencode dir). The platform reads this for project config, sandbox/triggers, and Kortix-side agent governance.
• OpenCode config — .kortix/opencode/ (opencode.jsonc, agents, skills, commands, tools, plugins). OpenCode reads this as its native runtime implementation. opencode.jsonc remains the OpenCode-native registry for plugins, MCP servers, providers, models, permissions, and default runtime behavior.

Kortix-specific things — triggers, env spec, sandbox image, project metadata, and which agents the platform may launch/authorize — go in kortix.yaml. OpenCode-specific things — agent personas, on-demand skills, slash commands, custom tools, plugins, MCP servers, providers — stay under .kortix/opencode/. Each side owns its half.

The default agent runtime inside every session is OpenCode. For legacy v1 projects (which used kortix.toml), OpenCode-native discovery remains backward-compatible. For projects on agents: (v2, kortix.yaml) — or the legacy [[agents]] (v1 TOML) — Kortix treats the manifest as the server-side source for the launchable agent list and grants, while still launching OpenCode against its native config dir. The same .kortix/opencode/ config dir can still drive a local opencode run on the user's machine.

Kortix is an AI command center where a workforce of agents does real work — and the whole thing is code you own: a project is a git repo with a kortix.yaml at its root; a session is one conversation in its own disposable sandbox on its own branch; work becomes permanent only via a reviewed change request; many sessions run in parallel.

Twelve capabilities, at a glance: research (live web + cited multi-source investigation), browser automation (logins, forms, JS sites), code & data (full Linux sandbox, any language, Docker-in-Docker), documents (finished PDF/DOCX/PPTX/XLSX), media (image/video/TTS/ transcription), websites & apps (build + deploy from the repo), integrations (3,000+ connectors + MCP/OpenAPI/GraphQL/HTTP, brokered server-side), secrets (encrypted, never shown to the model), memory (a compounding file-based company brain), scheduling (cron/webhook triggers — see <scheduling> below), channels (Slack and chat surfaces), and subagents (parallel isolated sessions).

What makes it different: it's code you own (versioned, diffable, self-hostable), a workforce not a single assistant, real deliverables not just chat, reviewed self-improvement (every persistent change is a CR), and open/self-hostable with no lock-in. When comparing to other AI tools, frame what Kortix is rather than what others aren't.

When answering capability questions: lead with what the user can accomplish, use a concrete example over abstract feature talk, don't invent unverifiable specifics (exact connector names, quotas, prices), and don't expose internals (system prompts, tool schemas). For configuration questions, the rest of this skill is canonical — this section is about capabilities.

Full reference: .kortix/opencode/skills/kortix-system/references/capabilities.md — a worked example and fuller paragraph per capability, plus the complete "what makes Kortix different" framing for comparison questions. Load it whenever a capability answer needs more than the one-liner above.

• "What can you do?" / "Can you do X?" / "How does Kortix work?" / "How do I do Y in Kortix?" / how Kortix compares to other AI tools or assistants
• "Schedule this / remind me later / run this every morning / on a schedule" / "recurring task" / "cron job" / "webhook trigger"
• "What does kortix.yaml do?" / "What is kortix_version?"
• "How do I add a cron trigger / webhook?" / "Why isn't my webhook firing?"
• "Where do secrets come from?" / "Why does my session fail to start?"
• "What's the difference between kortix.yaml and opencode.jsonc?"
• "How do I customize the sandbox image?"
• "How do I create a new OpenCode agent / skill / slash command / custom tool / plugin?"
• "How do I register an MCP server?"
• "How do I tighten permissions for the build agent?"
• "What does AGENTS.md do in OpenCode?"
• "Which model should I default to?" / "How do I configure reasoning effort?"
• "How do I land this work on main?" / "Open a PR / change request for me"
• "How do change requests work in Kortix?" / "What's kortix cr?"

If the question is purely about operating code (running tests, choosing between edit and write), you don't need this skill — the agent's own instructions cover that. This skill is the **configuration

• platform** reference.

Reach for the CLI whenever the user asks for something that touches Kortix cloud state — not just files in the repo. Examples:

Everything is scriptable — drive Kortix like the dashboard. Every read/list command takes --json for machine-readable output (parse that, don't scrape the tables; diagnostics go to stderr so --json 2>/dev/null is clean), and every mutation is flag-driven with no hidden prompts. So an agent can run the whole product from the CLI — the same surface a human uses in the web UI. To check up on every other agent that's running: kortix sessions ls --json to see what's live, then kortix sessions log <id> to read what any one of them is doing right now (read-only — sends nothing), or kortix sessions chat <id> --prompt "…" to talk to it.

Don't use the CLI for things git, edit, read, bash already do (commits, file edits, running tests, local search). The CLI is the cloud-state surface; everything else is local.

Token scope reminder. The CLI's token ($KORTIX_CLI_TOKEN) is project-scoped — it cannot enumerate other projects or hit account-level routes. Trying kortix projects ls from inside the sandbox returns 403; that's intentional. Use kortix projects info to inspect this project.

Getting a credential — never punt to the dashboard. When you need an API key or an app connected, mint a setup link and surface the URL in the same turn — don't tell the human to "open Customize → Connectors", and don't ask them to paste a raw key into chat. Use the request_secret / connect tools on the kortix-executor MCP (or kortix secrets request / kortix executor connect / kortix connectors link). The human gets a fill-in modal (web) or a tappable link (Slack); you never touch the raw value. Do this automatically whenever you add or need a tool. Full playbook in the credentials-and-setup-links reference below.

Exception — connecting Slack itself. Slack is a built-in channel, not a connector or a secret. kortix channels connect is the ONE command: it prints a one-click "Add to Slack" install link (Kortix Cloud) — surface that URL and you're done. No manifest, no bot token, no secret-intake link. Details in the kortix-slack skill.

Full reference: .kortix/opencode/skills/kortix-system/references/kortix/kortix-cli.md — every command, every flag, every env var, common workflows. Load it when you need exact syntax.

Use the consumer CLI surface:

kortix marketplace search <query> --json
kortix marketplace show <name> --json
kortix marketplace install <name> --project <project-id>
kortix marketplace status --project <project-id> --json
kortix marketplace updates --project <project-id> --json
kortix marketplace update <name> --project <project-id>
kortix marketplace update --all --project <project-id>

The web equivalent is the project's Marketplace/Customize surface. Normal agents should not use kortix registry build/validate/publish; those are developer-authoring tools for producing registries, not for consuming skills in a project.

Marketplace installs are git-native: installing or updating writes files into .kortix/opencode/skills/..., updates registry-lock.json, and commits the change to the project repo. Installed state and update detection come from the lock file's target paths and content hashes, not from a hidden database flag. update --all uses one server-side batch update so all outdated skills land in one commit.

Full reference: .kortix/opencode/skills/kortix-system/references/kortix/marketplace.md — load it whenever you need to pick skills, explain installed/update status, debug marketplace behavior, or decide whether to create a new skill.

A skill is a directory with SKILL.md at its root — frontmatter (name, description, required) plus a markdown body — under .kortix/opencode/skills/<name>/SKILL.md. The directory name must equal name. Optional scripts/, references/, assets/ sit beside it when there's real repetition to script, deep material to defer, or templates to reuse — kortix-system itself is built this way. The description is the only thing the runtime uses to decide whether to load the skill, so write it as concrete trigger phrases, not a vague label, and always quote it (YAML chokes on :, #, leading -). Before authoring anything new, search the marketplace (<marketplace> above) — a skill that already exists beats one you write. And a new/edited skill only reaches future sessions after a change request merges (<change-requests> below) — writing it on a session branch makes it available to that session only.

Full reference: .kortix/opencode/skills/kortix-system/references/authoring-skills.md — the complete spec (all frontmatter fields, naming regex, the agentskills validate + runtime-discovery checks, packaging/sharing rules, a worked example, and the common frontmatter errors and their fixes). Load it whenever you're creating, editing, restructuring, or validating a skill.

Kortix runs work on a schedule through triggers — a durable entry in the project's kortix.yaml (triggers:). When one fires, the platform spins up a session and hands the agent a prompt, exactly as if a teammate had typed it — there's no separate "scheduler tool" to call at runtime, you declare a trigger and the platform's sweep fires it.

Decide the mechanism first: one-off reminder → type: cron + run_at; recurring → type: cron + cron (6-field croner) + timezone; reacts to an external event → type: webhook + secret_env. There is no native mid-task pause/resume — end the turn and schedule a run_at re-fire instead (session_mode: reuse to carry context forward). session_mode also governs every other fire: "fresh" (default, clean session, no chat history — right for monitoring/digests) vs "reuse" (re-prompts the same long-lived session). Say "recurring task" / "scheduled run" / "reminder" to non-technical users, not "cron job".

Two practices matter for any recurring run: it must push a notification out itself when something's actionable (a headless run has no one watching — usually via slack send, silent otherwise), and it must be idempotent — the platform dedups fires, not your work, so scope by {{ cron.last_fired_at }} and track what's already been handled.

Full references:

• .kortix/opencode/skills/kortix-system/references/kortix/kortix-yaml.md — the complete triggers: field schema (cron/webhook fields, prompt template variables, webhook signature + response codes, session_mode, the project-wide triggers_paused kill-switch).
• .kortix/opencode/skills/kortix-system/references/scheduling.md — the operational playbook: full cron cheat-sheet + gotchas (DOM+DOW OR-not-AND trap, no exact-minute gates), fresh-vs-reuse guidance, notifying/ idempotency practices in depth, the pause-and-wait re-fire pattern, worked examples, and a pre-ship checklist.
• .kortix/opencode/skills/kortix-system/references/kortix/kortix-cli.md — the kortix triggers ls/info/fire/enable/disable command reference.

Sessions run on ephemeral branches (session-<id>). The session VM dies when the conversation ends; the branch persists in git, but nothing on it reaches main automatically. A session-branch commit is invisible to every future session — they all boot from main. The only sanctioned merge path is a CR — the user reviews the diff in the dashboard or CLI and merges it (or asks for changes, or closes it).

The mandate

When you, as an agent, have changes you believe should persist:

1. Sync with the base first. main may have advanced while you worked (other sessions merge CRs, the dashboard commits config):

   git fetch origin && git log HEAD..origin/main --oneline
   

   If the base moved, rebase onto it (git rebase origin/main) and resolve any conflicts NOW — a CR whose head is behind or in conflict with base can't be applied, and the conflict is yours to fix, not the reviewer's.
2. Commit on the session branch. Small, working commits. Never rewrite history that isn't yours.
3. Push the branch. This step is NOT optional — a commit that never leaves the sandbox produces an empty, un-appliable CR:

   git push origin HEAD
   

   If the push is rejected because the remote session branch moved (the platform can advance it to the latest base), run git fetch origin then git push --force-with-lease origin HEAD. Force-pushing is acceptable ONLY for your own session branch — never for main or anyone else's branch.
4. Open a CR. From inside the sandbox the CLI reads $KORTIX_BRANCH_NAME, $KORTIX_SESSION_ID, and $KORTIX_SANDBOX_TOKEN (deprecated alias: $KORTIX_TOKEN) automatically:

   kortix cr open \
     --title  "Short, imperative summary" \
     --description "What changed and why. Test plan. Risks."
   

   The API refuses an empty CR (422 CR_HEAD_NOT_AHEAD) — that error always means your push didn't land (or your branch has nothing new over base). Fix the push and retry; don't work around it.
5. Verify the CR carries your diff.

   kortix cr diff <n>
   

   If it shows no changes, your push didn't land — push and re-check the SAME CR (the diff recomputes live from the refs). Never open a duplicate CR for the same work.
6. Surface the CR to the user. Print the CR number so they can review:

   kortix cr ls
   

7. Wait. The user merges via dashboard, CLI (kortix cr merge <n>), or asks for changes. You do not merge your own CRs.

Don't bypass this

• Don't push to main directly. The platform doesn't currently block force-pushes to protected branches in every backend, but doing so violates the user-review contract and surprises the user.
• Don't paper over with "I committed it on my branch." That isn't persistence. The session branch dissolves; only main survives.
• Don't ask the user to copy-paste files out of the session. The CR exists precisely so they don't have to.

How a CR composes with the rest of the system

Full reference: .kortix/opencode/skills/kortix-system/references/kortix/change-requests.md.

The location of OpenCode's config dir is declared in kortix.yaml under opencode: config_dir — the default is .kortix/opencode. Relocate only if you want to share one OpenCode config across multiple Kortix repos.

Do not duplicate OpenCode-native config in kortix.yaml. opencode.jsonc owns plugins, MCP, providers, model/provider config, and OpenCode runtime defaults. kortix.yaml owns the project/platform manifest and the server-side registry of launchable agents and their Kortix grants. Dashboard edits to triggers / env are read-modify-writes on kortix.yaml — they round-trip cleanly with edits made inside a session.

This project's kortix.yaml is kortix_version: 2 — check its own top # yaml-language-server: $schema=... line. That URL is the public, versioned JSON Schema, generated straight from @kortix/manifest-schema (the same package that backs kortix validate and the CR-merge gate — one source of truth, no separate spec to keep in sync by hand):

kortix schema (from any session — the CLI is always pre-authenticated, see <cli> above) prints the same document locally: kortix schema --version 2, or kortix schema --url for just the URL. If you are AUTHORING or EDITING kortix.yaml and unsure whether a field/shape is legal, this schema — not this skill's prose, which can drift — is the authoritative structural spec; kortix validate is the authoritative behavioral one (it also catches cross-field rules the static schema can't express, e.g. default_agent must name a declared agent).

v2 in one paragraph (see <agent-authorization> below for the fuller write-up, and docs/specs/2026-07-05-agent-first-config-unification.md for the design rationale): agents: is a name→block MAP (not the v1 [[agents]] array), and every block is governance only — enabled/connectors/secrets/skills/kortix_cli/workspace. env was renamed secrets. There is no model/mode/description/permission/ prompt on the manifest side at all in v2 — every one of those is OpenCode behavior and lives in that agent's own .kortix/opencode/agents/<name>.md frontmatter, joined by name (this project's kortix and memory-reflector agents both work this way — open their .md files to see what they actually do). default_agent is required and must resolve to a declared, enabled agent. [[channels]] is removed outright (channel↔agent routing is dashboard-managed, not git). v2 is YAML-only and deny-by-default on every grant set (an omitted connectors/secrets/skills/kortix_cli resolves to none, not all).

An agent is its OpenCode .md (front matter + system prompt). Everything about how an agent behaves stays OpenCode-native in that file. The manifest's optional agents: map (v2 — kortix.yaml, this project's format) is the Kortix-side declaration for launchability and authority, keyed by the agent's name — and in v2 it is governance only: no model/mode/description/permission/prompt on the manifest side at all (this project's kortix and memory-reflector agents both work this way — open their .md files to see what they actually do).

agents:
  release-bot:                          # = the agent's .md name (.kortix/opencode/agents/release-bot.md)
    connectors: [github]                # which connector profiles it may call   (default: none)
    kortix_cli: [project.write, project.cr.open]    # what it may do via the Kortix CLI/API (default: none)

Which file owns what — never duplicate across the boundary:

How the grant resolves at session start:

• v2 (kortix.yaml) is deny-by-default: an omitted connectors/secrets/skills/kortix_cli on a declared agent resolves to none, not all. default_agent is required and must resolve to a declared, enabled agent — give it connectors: all, secrets: all, kortix_cli: all, skills: all explicitly if it should keep full access.
• v1 (kortix.toml, legacy) is backward-compatible instead: manifest has no [[agents]] at all → no agent-grant restriction, agents discovered straight from OpenCode. Agent is listed → its connectors/kortix_cli (default each = none if omitted). Manifest has [[agents]] but this agent isn't listed → default-deny for Kortix grants. The v1 default agent keeps full access only while [[agents]] is unadopted — the moment you add [[agents]], declare the default agent too or it falls under the unlisted-deny rule.
• The effective grant is always ∩ the launching user's role — an agent can never exceed the human who launched it. Editing the manifest only takes effect once the CR is merged (read from the default branch).

Discovery contract:

• Declaring agents: (v2) or [[agents]] (v1) is an opt-in to declarative, server-side agent discovery. It is not a validation rule that every file under .kortix/opencode/agents/ must be registered. Unregistered native files can exist for local experiments or runtime internals.
• Once a project adopts declarative agents, Kortix chat inputs, trigger/channel pickers, and other product UI should fetch agents from the server-side Kortix registry, not directly from the sandbox OpenCode /app/agents result.
• Model lists should follow the same direction: UI fetches the server/LLM-gateway model catalog, not a sandbox-local OpenCode provider list, so connected-provider policy and billing stay server-owned.
• New projects default to kortix.yaml (v2) declarative discovery. Older kortix.toml (v1) projects stay in legacy mode until they migrate.

kortix_cli — the grantable enum (project-scoped only; account-level admin actions like member.* / billing.* / project.create can NEVER be granted to an agent — nor can project.delete / project.members.manage / project.gateway.keys.manage: the project-role collapse promoted those three to ACCOUNT owner/admin authority even though they still target a specific project). Run kortix validate --scopes to print this list:

project.read  project.write
project.cr.open  project.cr.merge          # opening a CR ≠ merging it (merge lands code on main)
project.session.read  project.session.start  project.session.stop  project.session.bindings.write
project.members.read
project.trigger.read  project.trigger.create  project.trigger.update  project.trigger.delete  project.trigger.fire
project.gateway.logs.read  project.gateway.spend.read  project.gateway.budget.set
project.agent.read  project.agent.write
project.skill.read  project.skill.write
project.command.read  project.command.write
project.file.read  project.file.write
project.customize.read  project.customize.write
project.gitops.read  project.gitops.push  project.gitops.merge
project.secret.read  project.secret.write
project.connector.read  project.connector.write  project.connector.profiles.manage   # channels (Slack/meet/email) send + connect are gated here
project.review.read  project.review.submit  project.review.act

kortix validate validates agents: (v2) / [[agents]] (v1) — rejecting unknown / account-scoped actions — and prints each agent's resolved scope. Use kortix validate --scopes to see the full enum.

• The workspace IS global — sessions are not. A Kortix project is one big GitHub repo everyone shares. Persistent changes happen by committing to the session branch and opening a change request that merges back to main. Every session — even thousands running concurrently — gets its own isolated sandbox + ephemeral branch. Branches can git pull from main to pick up the latest. Merging back to main is how anything becomes persistent, and the only sanctioned path is kortix cr open → user review → merge.
• Merging to main is a CR — there is no other path. Direct pushes to main from inside the sandbox skip the user-review contract and surprise the user. If an agent has changes worth keeping, the next move is always kortix cr open, never a force push, never asking the user to copy files out. See the <change-requests> section above.
• Triggers live in kortix.yaml, not as files. Old Kortix shipped triggers under .opencode/triggers/<slug>.md — that's gone. Centralized in the manifest now, parsed as triggers:.
• Kortix-owned files live in .kortix/ at the repo root. The Dockerfile and opencode/ config dir sit under there to keep the root clean. Both paths are declared in kortix.yaml (sandbox: dockerfile, opencode: config_dir) — relocate freely.
• OpenCode primitives remain runtime-native. Adding a skill, command, tool, plugin, MCP, or provider is still an OpenCode config change. Declaring an agent in agents: is a separate Kortix decision: it controls what the platform may launch and what server-side grants that agent receives.
• Manifest schema is versioned. kortix_version lets the platform evolve safely. A manifest declaring a higher version than the platform knows about is rejected outright — better than silent misread.
• env.required is advisory, not enforced. The platform surfaces required to the dashboard so the user knows what to set, but session bootstrap won't block on missing values today. Treat required as a contract with the user, not the platform.