kortix-system

How Kortix works and how to change a Kortix workspace from a session: land work through a change request, drive Kortix with the in-sandbox `kortix` CLI, keep files where they last, store or request cr

SKILL.md

GitHub
<skill name="kortix-system"> <live-skills> ## Skills, served live Your system prompt lists every skill your agent may load, with its path. Read a skill's `SKILL.md` with `read` before you work on its topic. Paths inside a skill are relative to its folder. The Kortix skills (`kortix-*`) come from the deployed platform, not from the repository, and update in a running session. Never edit or commit a copy. For one your list lacks, or outside a session: - `kortix system-skills` lists them; `kortix system-skills get <name>` prints one `SKILL.md` and its reference paths; `… file <name> <path>` one reference. A flag-gated skill exists only while its flag is on. Optional skills: `kortix marketplace search <query>` (`kortix-marketplace`). </live-skills> <overview> ## The model - A **workspace** is a Git repository with `kortix.yaml` at its root. Kortix hosts it, or the workspace connects one on GitHub. - A **session** is one unit of agent work: one sandbox and one Git branch, `$KORTIX_BRANCH_NAME`. Sessions run in parallel and share no sandbox. - An **agent** is one block under `agents:` in `kortix.yaml`: prompt, model, permission rules, and the things it may use. - Every session starts from the default branch. A change reaches other sessions only when its change request merges. - `/workspace` starts empty: Kortix checks out the repository there only when your agent's `workspace.repos` declares a clone (your prompt then names it and its setup progress). Otherwise `kortix workspaces clone` clones the repository onto your session branch. Send the change with `kortix cr`. - Only your session branch accepts your push. The push needs `workspace.gitops.read` in your agent's `kortix_permissions`. - Asked what Kortix can do: answer as `references/capabilities.md` says. </overview> <machine> ## Your computer and where files last Your session runs on its own microVM: a whole Linux computer, root through `sudo`. `/MACHINE.md` lists its tools and explains its desktop. - `/workspace`: this session's files, kept for the life of the session. - `/drives` (Drive): your files and the company's, kept until deleted. Save what the user keeps in `/drives/me` (`kortix-drives`). No `/drives`: Drive is off. - Anything else (home, `/tmp`, installed packages) can be gone when the session reopens. To keep a package for every session, add it to a sandbox template (`references/kortix/kortix-yaml.md` → sandbox) and install it now too. - "My desktop": a file goes to `~/Desktop` (their Drive folder); a program goes on your screen, which the user watches in the **Desktop** panel, or on their own computer. The `kortix-computer` skill decides which (`<which-desktop>`). Keep big files out of Git: every clone downloads the whole repository. `kortix validate` warns at 10 MiB per file and at 512 MiB in total; above 512 MiB compressed, running sessions stop picking up config changes. Put media and datasets in object storage; add build output to `.gitignore`. </machine> <change-requests> ## Land work through a change request A commit that stays on your session branch reaches no other session. A change request (CR) is the only way to the default branch. Do every step: 0. Work in your clone (`<overview>`): `cd` into it and run every step there. 1. Sync: `git fetch origin && git rebase origin/main` (`main` or the default branch `kortix workspaces info` names). Resolve conflicts now. 2. Commit small, working commits. Run `kortix validate` after a `kortix.yaml` change. Keep big files out of Git (`<machine>`). 3. Push: `git push origin HEAD`. Rejected because the remote branch moved? `git fetch origin && git push --force-with-lease origin HEAD`. Force only your own session branch. 4. Open: `kortix cr open --title "<imperative summary>" --description "<what, why, how you tested, risks>"`. It takes `$KORTIX_BRANCH_NAME` as the head. `422 CR_HEAD_NOT_AHEAD` means the push did not land: push, then retry. 5. Check: `kortix cr diff <n>` shows your diff. Empty: push again and check the same CR. Never open a second CR for the same work. 6. Tell the user the CR number and title. The web app shows a **Review** button under your reply. Name `kortix cr merge <n>` only to a CLI or channel user. 7. Wait. Merge your own CR only when the user asks. The API refuses a self-merge (`403 CR_SELF_MERGE_REFUSED`) unless your agent holds `workspace.gitops.merge`. - Never push to the default branch, even when your grant allows it (`workspace.gitops.ref.any`): the push skips review. - "Committed on my branch" is not persisted. Never ask the user to copy files out of the sandbox. - A merge that changes `agents` or `default_agent` also needs `workspace.agent.write`; `triggers` needs `workspace.trigger.create|update|delete`. `503 CR_GOVERNANCE_UNVERIFIED`: nothing merged, retry after `Retry-After`. For people: https://kortix.com/docs/developers#change-requests </change-requests> <cli> ## The `kortix` CLI in the sandbox `kortix` is on `$PATH` and signed in: `$KORTIX_TOKEN` is this session's workspace-scoped token, `$KORTIX_API_URL` its API. Use it for Kortix cloud state. Use `git` and the file tools for files and commits. - Read commands take `--json`: parse it, never scrape tables. Diagnostics go to stderr. Mutations take flags and never prompt. - `kortix <group> --help` lists every subcommand and flag. Read it before you guess a flag. - The token cannot reach other workspaces or account routes (`kortix workspaces ls` answers `403`). `kortix whoami --token-only` prints your agent's grant. - Never send the user to a settings page for something the CLI does. For people: https://kortix.com/docs/developers#cli
Task Command
What every session does, talk to one kortix sessions status, sessions log <id> (read-only), sessions chat <id> --prompt "…"
Hand a task to another agent The agent tool (default session: "separate": its own session). From a session a person started it runs in the background: the report arrives later as a message. Deeper, one call waits up to 30 min. A follow-up goes to the same agent: send_message to its name, or agent with its task_id or name; a new agent only for separate parallel work. Not sessions new + wait-for
Tell another session something; a team's task list send_message (list_agents lists who you can reach), task_create/task_list/task_update (flag agent_teams; a teammate starts with agent({ name, team: true }), its role is for its session only); from a shell kortix sessions message <to> "…", sessions reachable, sessions inbound <id> accept|hold|refuse, kortix tasks ls|add|claim|done
Change requests, the review inbox kortix cr ls|show|diff|merge-preview, kortix review ls; My Kortix: the kortix_change_requests tool
Triggers; loops on this session (<scheduling>) kortix triggers ls|info|fire|add|set|enable|disable; kortix loop "…" --in 24h, kortix loops ls|pause|resume|rm
Secrets kortix secrets ls|set|request|sync
Connectors and accounts kortix connectors … (the kortix-connectors skill)
Apps: sites, servers, backends kortix apps … (the kortix-apps skill)
Drive files and sharing kortix drive … (the kortix-drives skill)
Connect Slack or Teams kortix channels connect (the kortix-slack skill)
Agents and models kortix agents ls|default|config|scope, kortix models ls|default <model-id>
Tools, feature flags kortix tools ls|eject <name>, kortix workspaces features [enable <flag>]
The manifest kortix validate [--scopes], kortix schema
Kortix itself is broken, confusing or missing something kortix feedback "<what happened, what you expected>" --kind bug|friction|idea: it reaches the Kortix team with this session's id. File it when it happens, once per problem, then continue with a workaround
</cli>
<credentials> ## Credentials: never send the user to a settings page
  1. Read $KORTIX_SECRET_CAPABILITIES first: a JSON list of the secrets this session may use, without values. Each entry's delivery:
    • sandbox: the named env var holds the real value. Never print, echo or write it to a file.
    • network: the env var holds a handle. Use it as the credential: Kortix puts in the value outside the sandbox, only on the listed hosts, over HTTPS. [REDACTED] in a response means it worked. Experimental.
    • https_broker: run the entry's command (kortix secrets call …).
    • kortix_service: a connector or the LLM gateway spends it. Nothing is in the sandbox.
  2. The user gave you a value (chat, a file): store it in the same turn, value on stdin: printf '%s' "$VALUE" | kortix secrets set NAME=- (--scope connector for a connector's key). 403: go to step 3.
  3. You lack the value: mint a link, put the URL in your reply, end the turn. A key your code reads: kortix secrets request NAME --scope runtime (the default scope, connector, never reaches the sandbox). An app account: kortix connectors connect <slug> --label "<name>" (--owner project for a shared company account). Never ask for a key in chat.

Slack is a channel, not a secret: kortix channels connect prints its install link. Owners, accounts, not granted, undecryptable: references/kortix/credentials-and-setup-links.md. </credentials>

<scheduling> ## Follow through: never wait blind

After any action whose result comes later (a message sent, an order or form submitted, a CR opened, a deploy started, a question to a person, a page to watch), set up this session's wake-up before you end the turn. Nobody asks.

You are now waiting on Wake this session with
A reply to an email or message A loop. Also a connector event when that app is connected (flag event_triggers): kortix triggers add "…" --on event --connector <slug> --event <TYPE> (types: kortix triggers events --connector <slug>)
A change request kortix triggers add "…" --on cr-merged --cr <id>
A deploy, a CI run, a job kortix triggers add "…" --on webhook --secret-env <NAME> when it can call a URL, else kortix loop "…" --every 15m
A person's answer kortix loop "…" --in 4h --every 6h
A page, a status or a price that changes on its own ("tell me whenever …") A watcher App that posts App events, then kortix triggers add "…" --on app --app <slug>: no model runs until it changes (references/scheduling.md → Watch 24/7). A loop only for a wait that ends within a day
A hand-off, a teammate, a workflow Nothing: it reports back by itself
  • Write the loop text for the turn that wakes: what you sent, to whom, what to check, what to do on each outcome, the end date (default 14 days). Tell the person in one line when you check and until when.
  • On each fire: check, act, report what changed. After empty checks, replace the loop with a slower one. Done or past the end date: kortix loops rm and kortix triggers rm every one. Playbook: references/scheduling.md.
  • Long jobs (many parts, many days): plan, delegate (agent, workflow), set the wake-ups, keep the state in out/status.md, set Kortix up when the work repeats, close out: references/scheduling.md → Long jobs.
Workspace work A kortix.yaml trigger (fields: references/kortix/kortix-yaml.md)
Recurring (a daily digest), or one-off on: { cron: "0 0 9 * * 1-5", timezone: <IANA> }, on: { every: 1h }, on: { at: <ISO-8601> }
Workspace code on a cadence, no agent run: { app: <slug>, path: /tick }
A system that can call a URL, or a watcher App on: { webhook: { secret: <SECRET_NAME> } }, on: { event, app }
  • A loop or a session trigger lives in the database: no CR. Every fire is a model turn. 403 feature_disabled: Loops are off. Tell the user (kortix workspaces features enable reminders). Meanwhile, an at trigger starts a fresh session at the time: put the full context in its prompt.
  • kortix triggers add|rm|enable|disable edit kortix.yaml: a trigger fires after its CR merges, or at once with --apply (through the API, gated by your kortix_permissions). Then kortix triggers fire <slug> once.
  • Nobody watches a scheduled run: push what matters, stay silent otherwise.
  • Say "scheduled run" or "loop" to people, not "cron job".</scheduling>
<runtime> ## The session runtime: pi

Every session runs pi inside the Kortix daemon. Every model call goes through the Kortix LLM gateway. pi has:

  • bash, read, write, edit on /workspace; glob, grep, question.
  • The Kortix tools web_search, image_search, image_gen, scrape_webpage, show (memory is retired: use the file tools); workspace tools; codemode.
  • Subagents through agent (the agents your subagents grant names; name one to message it, task_stop stops it); send_message, list_agents.
  • Compaction near the context limit and on demand (kortix sessions compact <id>); steering: a message sent during a turn is read at its next step.
  • Slash commands from commands: and granted skills; pi extensions and packages from extensions:.

pi does not have rewind or edit-and-resend (501 feature_not_supported), MCP servers (use connectors), a todo list, shell turns, session fork, or an attachable terminal client. No webfetch: use scrape_webpage. Its capabilities include session.subagents, session.compact, session.commands, session.steer, session.messaging, session.team_tasks. Say plainly what is missing.

pi puts the root AGENTS.md (else CLAUDE.md) in every system prompt. It reads that file, agents, skills, tools and commands from the default branch's config release: a change takes effect after its CR merges, in running sessions too. Extensions and codemode load at runtime start. Tools, permissions, extensions: references/pi.md. </runtime>

<manifest> ## kortix.yaml

One format, no version line. Declare everything in kortix.yaml (or kortix.yml) and the files it names. The workspace registers things by name; each agent enables what it uses. Unknown keys are errors.

# yaml-language-server: $schema=https://kortix.com/schema/kortix.schema.json
default_agent: kortix
env: { optional: [ORDERS_API_KEY] }       # secret names; values live in Kortix
skills: { triage: skills/triage }         # folder that holds triage/SKILL.md
tools: { lookup_order: tools/lookup_order.ts }
commands:
  standup: { description: Post the standup summary., prompt_file: commands/standup.md }
extensions: { audit: { pi: extensions/audit.ts } }   # or "npm:<package>@1.2.3"
agents:
  kortix:
    description: Front-door agent.
    mode: primary                         # primary | subagent | all
    prompt_file: agents/kortix.md         # or prompt: "…"
    permission: { bash: { "git push --force *": ask, "*": allow } }
    tools: "*"                            # "*" is every name; `all` is the same
    skills: "*"                           # omitted = none, Kortix skills too
    subagents: [researcher]
    commands: [standup]
    extensions: [audit]
    connectors: "*"
    secrets: [ORDERS_API_KEY]
    kortix_permissions: [workspace.read, workspace.gitops.read, workspace.gitops.push]
  researcher:
    mode: subagent
    prompt: Research the question. Cite every source.
    tools: [read, grep, web_search, scrape_webpage]
    skills: [kortix-system, triage]
triggers:
  - slug: daily-digest
    on: { cron: "0 0 9 * * 1-5", timezone: Europe/Berlin }
    run: { agent: kortix, prompt: "Summarize yesterday's merged change requests." }
  • agents, default_agent optional. My Kortix runs only with builtin_agents: { my_kortix: true }. No agent named runs default_agent (may be mykortix when on), else My Kortix when on.
  • An agent gets nothing it does not grant. Without skills it loads no skill, kortix-system included. skills and extensions also take { exclude: [names] }: every one but those.
  • A grant is all, none or a list of registered names. subagents names declared agents with mode: subagent or all.
  • tools: set it on every agent: all, none, a list, or { exclude: [names] }. Omitted, the agent gets every tool and kortix validate warns. A tools: registry entry with a Kortix tool's name replaces that tool.
  • permission: per key allow | ask | deny, or a pattern map where the longest matching pattern wins. Omitted: allow.
  • kortix_permissions: what the agent may do to the workspace. kortix validate --scopes lists the values. You grant only what you hold.
  • env.required is advisory: a session starts without the value.
  • A skill: skills/<name>/SKILL.md, the folder named like the skill, not kortix-*; frontmatter name and a quoted description that says when to load it. Register it, grant it, land it through a CR.
  • Connectors: the kortix-connectors skill. Apps: the kortix-apps skill.
  • Check every edit: kortix validate exits 0. Each issue names <file>:<line>:<col> and the fix. kortix schema prints the full schema.
  • A running workspace never stops on an error: it turns off or drops the broken part (references/kortix/kortix-yaml.md → Problems).
  • When your system prompt lists kortix.yaml issues, tell the user and fix them through a CR when asked. kortix validate --fix rewrites every deprecated shape, and converts an older format (fix: legacy-format). Keep every file that conversion writes or deletes.

Keys, imports:, sandbox templates, triggers: references/kortix/kortix-yaml.md. Tools: references/kortix/tools.md. People: https://kortix.com/docs/developers#kortixyaml-reference </manifest> Model switches, agent-pin permissions and precedence: references/session-model.md. </skill>