Developers

Build on Kortix: the CLI, git and change requests, the kortix.yaml reference, the REST API, Apps, self-hosting and the @kortix/sdk.

Everything a developer needs to build on Kortix, on one page: the CLI and git workflow, the kortix.yaml reference, the REST API, Apps, self-hosting, and the TypeScript SDK with its React hooks and UI components. For what Kortix is and how people use it, read the Guide.

Quickstart

Go from an empty terminal to a merged change request. Every step is a git operation on your project’s repository:

Install the CLI

curl -fsSL https://kortix.com/install | bash

The script supports macOS and Linux on x86_64 and arm64. On Windows, run it inside WSL. To pin a version or use the dev channel, see CLI → Install.

Sign in

kortix login

Your browser opens. Approve the CLI there. The CLI then picks your account and a default project.

With one project, the CLI picks that project. With several, it asks. With none, it skips this step.

On a machine without a browser, sign in with a token: kortix login --token kortix_pat_…. The token kinds are in Use any git client.

Create or get a project

A project is a git repository with a kortix.yaml at its root. Create one, or clone one a teammate made.

kortix init my-agent
cd my-agent
kortix ship

kortix projects ls --all
kortix projects clone <project_id> my-agent
cd my-agent

What a new project contains

kortix init and a new repository from Create project start from the same starter:

my-agent/
├── kortix.yaml        the manifest (kortix_version: 3): skills, agents, one trigger, secret names
├── agents/            the prompt of each agent: kortix.md, harness-reflector.md, session-reviewer.md
├── skills/            11 skills, one folder each, with a SKILL.md
├── memory/MEMORY.md   the project memory
├── README.md
└── .gitignore

• kortix is the default agent. Every grant it has is all.
• harness-reflector refines the agents’ prompts, skills and tools from recent sessions, through one change request. Its daily trigger is off until you set enabled: true.
• session-reviewer is a subagent of harness-reflector.
• All three set workspace: { project_repository: true }, so each session gets a checkout of the repository on its own branch in /workspace.
• The Kortix skills (kortix-*) are always registered. The skills key in kortix.yaml lists the other 10.

kortix init also writes files for the coding tools you picked. Codex, pi and Cursor get AGENTS.md. Codex, Claude Code and pi get a link to skills/ in .agents/, .claude/ or .pi/. Every key is in the kortix.yaml reference.

Run a session

A session is one unit of agent work. It runs in its own sandbox, on its own branch.

kortix sessions new --prompt "Add a skill that drafts the weekly status report"

The session runs the project’s default agent, kortix. --agent <name> and --model <id> override the agent and the model. In a terminal, the CLI then prints the kortix sessions chat command for the new session. In the web app, type the prompt on the project page.

On the Credits plan or Enterprise, a session runs on the platform default model. On Free, connect your own provider key or a ChatGPT subscription first. See Models.

Review and merge

A change request proposes to merge the session branch into the default branch (main in a new project). Kortix does not open a change request by itself.

The Kortix skill kortix-system tells the agent to push, open one with kortix cr open, and wait. The starter agents may load it: their skills grant is all. If the agent did not open one, ask it to, or open it yourself:

kortix cr open --head <session_id> --session <session_id> --title "Weekly status report skill"

Then review and merge:

kortix cr ls          # open change requests
kortix cr diff 1      # the unified diff
kortix cr merge 1     # merge into the base branch
git pull              # bring the merged work into your clone

1 is the change request number from kortix cr ls. To send the work back, run kortix cr request-changes 1 --message "…". The note goes to the change request’s session and wakes it if it sleeps. In the web app, use the project’s Review page.

The starter kortix agent holds kortix_permissions: all, so the API lets it merge its own change request. The kortix-system skill tells it to wait until you ask. Who may merge: Agents that merge.

Check your setup

kortix doctor

kortix doctor checks your login and the project. Then it starts a throwaway session, sends ping, waits for the agent’s reply, and deletes the session. It exits 1 when a check fails. --no-session stops after the login and project checks.

Next steps

Git

Every Kortix project is one git repository. You clone it and push to it with any git client. You fetch the branch of each session, and land work on the base branch through change requests. This section is for everyone who works on project files outside the web app, and for admins who decide who may push.

The shortest path from a project to a reviewed change:

kortix projects clone <project_id> my-project
cd my-project
git checkout -b tighten-triage
# edit agents/, skills/ or kortix.yaml
git commit -am "Tighten the triage prompt"
git push origin tighten-triage
kortix cr open --head tighten-triage --title "Tighten the triage prompt"

Your project’s repository

A project has one of two kinds of repository. Both work the same way after the project exists.

On a self-hosted instance, a platform admin sets up managed repositories in the admin console. GET /v1/projects/managed-git/status returns configured: false until then, and the new-project form says “Kortix-managed repositories are not available on this instance.” See Self-hosting.

The git origin

Every project has one clone URL, whatever its kind:

https://<api-host>/v1/git/<project_id>.git

On Kortix Cloud this is https://api.kortix.com/v1/git/<project_id>.git. Find it in two places:

• kortix projects info <project_id> --json, field git_origin_url.
• Customize → Settings → Git repo → Use your own Git client → Clone address.

Clone git_origin_url, not repo_url. repo_url is the upstream repository that Kortix forwards to.

• The origin speaks git over HTTPS only.
• You authenticate with a Kortix token. Kortix adds the upstream credential on the server. No GitHub or other provider credential reaches your computer or a sandbox.
• The audit log records each clone and fetch as git.clone and each push as git.push. See Audit log.

Clone a project

Customize → Settings → Git repo → Work on this locally shows the same three steps with the commands filled in.

The clone does three things:

1. It runs git clone with your token in the process environment. The token is never in the remote URL or in .git/config.
2. It writes .kortix/link.json, which binds the folder to the project for kortix commands. It adds the file to .git/info/exclude, so the link stays on your computer.
3. It installs a credential helper for the origin, in the repository’s own .git/config:

[credential "https://api.kortix.com/v1/git/<project_id>.git"]
	helper =
	helper = !kortix git-credential
[credential]
	useHttpPath = true

The empty helper = line turns off every helper you configured elsewhere for this URL, so your keychain never stores the Kortix token. kortix git-credential gives git the token of your stored login each time git asks. After the clone, plain git pull and git push work. If that login is gone, git stops with Kortix Git needs login. Run: kortix login, plus --host <name> when the link names a host.

The clone writes the link and the helper only when the repository root has .kortix/, kortix.yaml or kortix.yml. In any other repository, create a .kortix/ folder at the root, then wire them by hand as in Wire the helper by hand.

Use any git client

The origin accepts HTTP Basic authentication. The username can be anything; the convention is x-access-token. The password is a Kortix token.

git clone https://api.kortix.com/v1/git/<project_id>.git
# Username: x-access-token
# Password: kortix_pat_…

Plain git saves the password in the credential store you configured. To keep the token out of every store, send it as a header on each command instead:

git -c http.extraHeader="Authorization: Bearer $KORTIX_GIT_TOKEN" clone https://api.kortix.com/v1/git/<project_id>.git

Security explains how to create and revoke keys.

Wire the helper by hand

Run these at the root of the checkout. kortix projects link refuses a folder without .kortix/ or kortix.yaml. The helper answers only for the URL that equals the project’s git_origin_url.

ORIGIN=https://api.kortix.com/v1/git/<project_id>.git
git config --local --replace-all credential.$ORIGIN.helper ''
git config --local --add credential.$ORIGIN.helper '!kortix git-credential'
git config --local credential.useHttpPath true
kortix projects link <project_id>

kortix projects link writes .kortix/link.json. The helper reads it to find the project and the host.

From CI

Create a project CLI token with kortix projects cli-tokens new and store it as a CI secret. The token acts as the person who created it, so that person needs push access to push.

AUTH="Authorization: Bearer $KORTIX_GIT_TOKEN"
git -c http.extraHeader="$AUTH" clone https://api.kortix.com/v1/git/$PROJECT_ID.git project
cd project
# change files, then commit
git -c http.extraHeader="$AUTH" push origin HEAD:refs/heads/ci-update

Errors from the origin

Commit and push

After a clone, commit and push with plain git. kortix ship runs these steps in one command:

1. It runs the kortix validate checks. --no-verify skips them.
2. It runs git add -A and commits, with the message from -m. The default message is kortix: ship. --no-commit fails when the working tree has changes.
3. It offers to set each env secret that has no value. --no-env skips this.
4. It pushes the current branch to the branch of the same name.
5. It connects each declared connector that still needs sign-in. --no-connect skips this.

-n / --dry-run prints the plan and changes nothing. kortix deploy is an alias.

The first ship

A folder with no .kortix/link.json gets a new project, unless the CLI has a default project. kortix login and kortix projects use set one. Ship then pushes to the default project instead. kortix projects unset clears the default.

For a new project, ship picks the repository from the folder’s origin, without a prompt:

For a GitHub URL, the first ship pushes to your existing origin with your own git credentials.

--origin <github-url> sets origin to that GitHub URL first. --account <id|slug> picks the account, and --name the project name.

Ship writes .kortix/link.json the moment the project exists, and git add -A commits it. A teammate with push access (project.gitops.push, the Manager role) who clones the repository can then run kortix ship too. Later ships set origin to the project’s git origin and install the credential helper.

Who can clone and push

Five permissions control git:

A project Member holds project.gitops.read only. A Member reads the branches, commits and change requests of the sessions they may open. A Member reads nothing of another member’s private session.

A clone serves every branch, so a person needs project.gitops.push to clone or fetch. A Member cannot clone from their own git client. A Member’s sessions still clone and push their own branch.

A Manager holds all five. Account owners and admins act as Managers on every project in the account. See Teams.

People with push access:

• may push any branch, including the default branch;
• need project.gitops.ref.delete to delete a branch;
• can never delete the default branch. Nobody can.

IP allowlist and MFA policies of the account apply to git requests too.

Sessions push with the session token:

• A session pushes only its own branch, the branch named after its session_id.
• Any other branch needs project.gitops.ref.any in the agent’s kortix_permissions. Deleting a branch needs project.gitops.ref.delete.
• A push to the default branch also needs project.agent.write, project.trigger.create, project.trigger.update and project.trigger.delete.
• The agent’s kortix_permissions must list the permission, or be all, and the agent’s ceiling role must also hold it. Neither widens the other. The role of the person who started the session is not an input. An agent with no kortix_permissions key holds no project permission. See What an agent may do.

By default, agents land work through change requests. Agents shows how to grant permissions.

Kortix does not block a force-push. On a GitHub repository, add a ruleset that blocks force-pushes and deletions on the default branch. The ruleset does not block change-request merges, because a merge is a fast-forward or a merge commit.

Read a refused push

Kortix refuses the whole push when it refuses one ref. Git prints the reason for each ref:

 ! [remote rejected] HEAD -> feature-x (a session may only push its own branch (<session_id>); commit there and open a change request to land this elsewhere)

Session branches

Each session works on its own branch. The branch name is the session_id, with no prefix. Kortix cuts the branch from the session’s base_ref, which is the project default branch unless the session was created with another one.

A session gets the branch and a checkout in /workspace only when its agent sets workspace: { project_repository: true }. The starter agents set it. Without it, repository calls answer 403 session_repository_access_denied.

Inside the sandbox, the branch is $KORTIX_BRANCH_NAME. The agent commits there and runs git push origin HEAD. Inside a session sandbox lists the other variables.

A pushed branch stays in the repository after the session stops and after the session is deleted. /workspace holds this session’s files, kept for the life of the session. Work the agent did not push is gone when the session is deleted. See Computers.

Get an agent’s work on your computer:

git fetch origin <session_id>
git checkout <session_id>

• kortix files branches lists the branches with commits ahead of and behind the default branch.
• kortix sessions info <session_id> shows branch and base_ref.
• To start a session on another branch, pass base_ref when you create it, in POST /v1/projects/<project_id>/sessions or in sessions.create() of the SDK. kortix sessions new has no flag for it.

When the base branch moves, open the command palette in the session and run Ask Agent: Sync Branch & Reload. The agent merges origin/<base_ref> into the session branch, resolves conflicts, runs the relevant tests, and commits. Its last command is kortix sessions reload … --no-repo --force --yes, which restarts the agent runtime and ends the turn. Send continue when the runtime is back.

Change requests

A change request merges one branch, the head, into another, the base. Kortix runs the merge, the diff and the conflict check as git operations on the project repository. So change requests work on every kind of repository.

open ──merge──▶ merged          (final)
open ──close──▶ closed ──reopen──▶ open

Open one from your computer

git push origin my-branch
kortix cr open --head my-branch --title "Add the triage agent" --description "Why and what changed"

• The base is the project default branch. --base <branch> targets another branch.
• A head with no commits ahead of the base is refused with CR_HEAD_NOT_AHEAD. Push first.
• Each later push to the head branch updates the same change request.

Open one from a session

An agent follows this contract:

1. Commit on $KORTIX_BRANCH_NAME.
2. Push: git push origin HEAD.
3. Open: kortix cr open --title "…" --description "…". Inside a sandbox, --head and --session fill themselves from $KORTIX_BRANCH_NAME and $KORTIX_SESSION_ID.
4. Report the change request number to the person, and stop.

A change request from a session targets the session’s base_ref. An agent cannot retarget it: --base with another branch returns 400 CR_BASE_NOT_SESSION_BASE. A person can open a change request for the same head with --base.

Review and merge

Review in the web app on the Review page, or from a terminal:

kortix cr ls                     # open change requests
kortix cr diff 3                 # the unified diff
kortix cr merge-preview 3        # can it merge? lists conflicts
kortix cr merge 3
kortix cr request-changes 3 --message "Rename the flag first"

A merge runs these steps:

1. Kortix validates kortix.yaml on the head branch, with its imports:. An invalid manifest stops the merge with 422 MANIFEST_INVALID. A head with no manifest passes.
2. Kortix fast-forwards the base when the head is strictly ahead.
3. Otherwise it creates a merge commit, Merge CR #<n>: <title>, authored by Kortix <noreply@kortix.ai>. --message sets another message.
4. A conflict stops the merge with 409 and the list of conflicting files.

A merge can carry the commits of other open change requests on the same base. Example: you merge the top request of a stack, and the requests below it land with it. Kortix marks each of those requests merged, with the same merge commit. The response lists them in also_merged, and kortix cr merge prints Also merged #<n>.

After the merge, running sessions on that base pick up the new config, and Kortix syncs the project’s connectors from the new kortix.yaml. See Config comes from the base branch.

Request changes records the note on the change request and sends it to the session that opened it as a new prompt. A sleeping sandbox wakes.

Agents that merge

• An agent that declares kortix_permissions merges only when the grant includes project.gitops.merge. An agent without kortix_permissions cannot merge.
• A session cannot merge a change request it opened unless its grant in kortix.yaml includes project.gitops.merge. Without it, the merge returns 403 CR_SELF_MERGE_REFUSED.
• A merge that changes agents, default_agent or triggers also needs the permission the direct edit needs: project.agent.write, or project.trigger.create, .update or .delete. The merging agent cannot grant any permission it does not hold.

A grant that names project.cr.open or project.cr.merge counts as project.gitops.push or project.gitops.merge. Write the gitops name in new grants.

Permissions

kortix cr commands

<cr> is the change request number, such as 3, or its UUID.

Each command takes --project <id> and --host <name>. ls, show, diff, merge-preview, request-changes and version-diff also take --json. The REST routes are under /v1/projects/<project_id>/change-requests in the API reference.

GET /change-requests returns one page, newest number first: 50 change requests by default, at most 500 with limit (a larger limit answers 400). Pass next_cursor back as cursor for the next page; it is null on the last page. kortix cr ls follows it and lists every change request.

Errors

The Review page

The Review page is the project’s inbox for everything that waits on a person. Open Customize → Review in the project sidebar, or go to /projects/<project_id>/customize/review.

The lists are Needs you, Waiting and Done. The filters are All, Changes, Approvals, Outputs, Questions and Finished. Keys: j and k move, Enter opens, a approves, e asks for changes, d dismisses, 1 2 3 switch lists, / searches, ? shows help.

A change opens as a page, with its diff. Every other item opens in a dialog over the list, the way an approval does. Esc closes it.

An output shows the agent’s note, then what the agent made: the first image, video or audio file under /drives/ plays in the dialog, the preview text shows as its description, and each other file is a row that opens it. An output that names no file shows only its note.

Each list loads 50 items at a time, newest first. Load more shows the next 50. The filters and the search apply to the items loaded so far. The Review count in the sidebar, and the dot on a session that waits on you, count every item that needs you.

What a verdict does depends on the item:

An item an agent submitted takes every verdict: approve, reject, changes, answer and dismiss.

The Review page shows a verdict only to a role that holds its permissions. Every verdict on a change or on an agent’s item needs write access to the project (project.write):

A built-in member holds none of these permissions. It sees changes and agent items without verdicts, and it decides a connector approval only in a session it launched.

The change request dialog on the Files page and on a session’s change card follows the same rule. Apply changes and Fix with agent need project.write + project.gitops.merge. Dismiss and Reopen need project.write.

An output names its files in --detail. files takes {"path", "note"} objects or plain paths:

kortix review submit --kind output --title "Launch video" \
  --summary "Draft cut. Check the claims before you publish." \
  --detail '{"files":[{"path":"/drives/me/launch/cut.mp4"},{"path":"/drives/me/launch/sources.json","note":"Sources"}],"preview":"The post text."}'

The Review page also reads artifact, description and every other key whose value is a file path under /drives/ or /workspace/, named after its key. A file under /drives/ opens through the session that submitted the item. A file under /workspace/ is listed and does not open: the Review page has no running sandbox.

Reading needs project.review.read, a verdict needs project.review.act, and submit needs project.review.submit. A Member holds read and submit. A Manager holds all three.

The REST routes are under /v1/projects/<project_id>/review:

Config comes from the base branch

A session runs the current config release of its base branch: kortix.yaml and the files it registers. Those are agent prompts, skills, tools, commands and extensions. It does not run the files in /workspace.

• An edit in /workspace or on a session branch takes effect only when it lands on the base branch, through a merge or a push.
• Each commit on the base branch is a new config release. A running session converges to it at the start of its next turn. A push or a merge also starts the convergence in the background.
• To apply it at once, select Reload config in the session menu, or run kortix sessions reload <session_id>. It restarts the agent runtime. --force reloads during a turn and ends that turn; it asks first unless you pass --yes. --no-repo skips the git pull in /workspace. --status only reports whether the session is behind.
• To test config before a merge, create a session with base_ref set to your branch. Its change requests target that branch too.
• Such a session runs the branch’s agent behavior: each agent’s prompt, model and permission rules, and the skills, tools, commands and extensions it enables. Governance still comes from the default branch: which agents are declared, and their secret, connector and permission grants. A branch cannot widen what an agent may use before it merges. When the project requires declared agents, an agent declared only on the branch is refused with 400 AGENT_NOT_DECLARED.

When a release fails to load, the session runs the last release that worked, or else the platform default config. The session header shows Older config. Kortix does not retry the failed release until the base branch changes. Fix the config on the base branch: kortix validate checks the manifest.

To keep a file in git but out of the release, mark it export-ignore in .gitattributes. A directory rule covers everything under it. The release, the kortix validate size check and session config downloads leave those files out. The manifest file always ships whole.

fixtures export-ignore
datasets/raw export-ignore

Manage the repository

Customize → Settings → Git repo shows the repository, its Status, the Base branch and the Manifest file. It also holds Work on this locally, Use your own Git client and People with access. The base branch is the branch new sessions and change requests start from.

From the CLI, kortix projects set --branch <branch> and --manifest <path> change the same fields. Both need project.settings.write.

GitHub connection

GET /v1/projects/<project_id>/git/connection returns the connection state:

Repository disconnected

Kortix reaches a GitHub repository through the Kortix GitHub App installed on the repository’s owner. When that access goes away, the project is disconnected. GET /v1/projects/<project_id>/git/connection then returns state: reconnect_required, reason: repository_disconnected, a disconnected_reason, a message with the cause and the fix, and an install_url.

While a project is disconnected:

• Every API route that reads the repository answers 409 with code: repository_disconnected, the reason, and the same message. The project detail still loads: its config.manifest_version.unknown_reason is repository_disconnected and git_connection.status is error.
• Session create and start fail at once with that 409. A session that is already running keeps running.
• Scheduled triggers skip each run and record the message as the trigger’s last error. They do not retry.
• git clone, fetch and push through the Kortix git origin print the message as remote: ….
• The web app shows GitHub disconnected in the sidebar, in Git repo and on a session that cannot start. kortix projects info prints the reason and the reconnect link.

Kortix checks GitHub again at most every 5 minutes. After the fix on GitHub, the project reconnects on the next check. Reconnecting through Reconnect GitHub checks at once, and a project that stored the old installation moves to the new one.

Replace the repository

Under Git repo, select Change and enter the new GitHub repository URL. Kortix verifies access through the GitHub App. The new repository needs the manifest file on its default branch.

Stop active sessions, and close or merge open change requests, first. New sessions use the new repository. Existing sessions cannot restart after the change.

The route is PUT /v1/projects/<project_id>/git/repository. It needs project.settings.write and project.connector.write.

Give people direct access

A managed repository lives on GitHub under Kortix. To let someone work on it on github.com, add their GitHub username under People with access, with Can edit or Can view. GitHub emails them an invite.

This needs project.members.manage, and works on managed repositories only. For a repository you own, manage access on GitHub.

A repository on another git host

To let Kortix reach a repository on another git host, store a token with PUT /v1/projects/<project_id>/git-credential and the body { "token": "…" }. Kortix keeps it as a platform credential, not as a secret a sandbox can read. It needs project.connector.write. GitHub and managed repositories refuse it with 409.

For a repository on another git host, kortix sessions new run in a checkout whose origin is that repository creates the session branch. It pushes your current branch with your own git credentials.

Browse without a clone

kortix files reads the committed repository. It acts on the default branch unless --ref <branch|tag|sha> picks another. Every subcommand needs project.file.read.

For uncommitted files in a running sandbox, use kortix sessions cp <session_id>:<path> <dst>. See Computers.

Delete

kortix projects rm <project_id> deletes a project. It needs project.delete. Deleting a project deletes its managed repository. A repository you connected yourself is left untouched.

Through the API, DELETE /v1/projects/<project-id> answers { "ok": true, "deleted": true, "repo_deleted": <bool> }. repo_deleted says whether a managed repository went with it. The response also carries archived: true for older clients; it means the same as deleted, and there is no restore.

kortix.yaml reference

kortix.yaml is the manifest at the root of a project repository. It defines the project’s agents and everything each agent may use. This section lists every key of kortix_version: 3.

The smallest useful manifest:

# yaml-language-server: $schema=https://kortix.com/schema/kortix.v3.schema.json
kortix_version: 3
default_agent: assistant

agents:
  assistant:
    description: Answers questions about the project.
    prompt: You answer questions about this project. Read the files before you answer.
    skills: all                              # omitted: no skills
    workspace: { project_repository: true }  # omitted: no repository in /workspace

Every other key is optional. This agent may call every tool, and no tool call waits for a person: an omitted permission is allow.

File and schema

Put kortix.yaml at the root of the project repository. Start it with the schema line, so a YAML editor validates and completes every key:

# yaml-language-server: $schema=https://kortix.com/schema/kortix.v3.schema.json

kortix schema --version 3 prints the same schema. kortix schema --version 3 --url prints its URL.

Validate before you push:

kortix validate                                  # ./kortix.yaml and its imports
kortix validate --file config/kortix.yaml --json
kortix validate --scopes                         # every grantable kortix_permissions entry

• kortix validate exits 0 with no errors, 1 with one or more errors, and 2 when the file is missing or unreadable.
• kortix ship runs the same checks before it commits.
• The change request merge runs the schema check on the merged manifest. An error blocks the merge with 422 MANIFEST_INVALID. A warning never blocks.
• An unknown key is an error. This holds at the top level and in agent blocks, commands, extensions, workspace, App blocks, trigger on and run, and imported files. The message names the key that replaces it, when one exists. An unknown key under env is a warning.

kortix validate and kortix ship also check the files around the manifest. Each of these is an error:

• an agent or command prompt_file that does not exist;
• a skills folder with no SKILL.md, or a SKILL.md whose frontmatter name: is not the skill name;
• a tools module or an extensions.<name>.pi repository path that does not exist;
• an agent connectors or connectors_required slug that connectors does not declare (kortix_slack, kortix_teams, kortix_email and computer always count as declared);
• an agent secrets name or a trigger secret_env that env does not declare.

They warn when the files in Git exceed 512 MiB, or when one file reaches 10 MiB.

Example project

A support project: two agents, one skill, one tool, two commands, one extension, one connector with a read-only rule set, and a weekly trigger.

# yaml-language-server: $schema=https://kortix.com/schema/kortix.v3.schema.json
kortix_version: 3
default_agent: support

project:
  name: support-desk
  description: Answers help desk tickets.

env:
  required: [HELPDESK_TOKEN]
  optional: [STRIPE_API_KEY]

sandbox:
  default: python
  templates:
    - slug: python
      name: Python 3.12
      image: python:3.12-slim
      cpu: 2
      memory: 4

# Registries: what the project has. A registry entry gives nothing to any agent.
skills:
  refund-policy: skills/refund-policy

tools:
  lookup_order: tools/lookup_order.ts

commands:
  triage:
    description: Sort a ticket by urgency.
    prompt: "Read ticket $1 and reply with its urgency: low, normal or high."
  weekly-report:
    description: Write the weekly support report.
    prompt_file: commands/weekly-report.md

extensions:
  web-access:
    pi: npm:pi-web-access@0.30.0

connectors:
  - slug: helpdesk
    provider: http
    base_url: https://helpdesk.example.com/api
    auth:
      type: bearer
    policy_sets:
      read-only:
        description: Reads only.
        policies:
          - match: "get_*"
            action: always_run
          - match: "*"
            action: block

policy:
  default_mode: risk
policies:
  - match: "helpdesk.delete_*"
    action: block
approvals:
  ttl: 4h

# Agents: each one enables registered things by name.
agents:
  support:
    description: Answers help desk tickets.
    mode: primary
    prompt_file: agents/support.md
    permission:
      bash:
        "*": allow
        "git push *": ask
    skills: [refund-policy, kortix-cli]
    subagents: [researcher]
    commands: all
    extensions: [web-access]
    connectors: [helpdesk]
    secrets: [HELPDESK_TOKEN]
    kortix_permissions: [project.session.read, project.gitops.push]
    workspace: { project_repository: true }
  researcher:
    description: Looks up an order's history. Never edits files.
    mode: subagent
    prompt: You research orders and report what you find. Never edit files.
    permission:
      edit: deny
    tools: [read, glob, grep, lookup_order, web_search]
    connectors: [helpdesk]
    policy_sets:
      helpdesk: read-only

triggers:
  - slug: weekly-report
    name: Weekly report
    on:
      cron: "0 0 9 * * 1"
      timezone: Europe/Berlin
    run:
      agent: support
      prompt: Write the weekly support report for the last 7 days.

The repository also holds agents/support.md (the prompt), skills/refund-policy/SKILL.md (with name: refund-policy), commands/weekly-report.md and the tool module:

// tools/lookup_order.ts
export default {
  description: 'Look up an order by id.',
  parameters: {
    type: 'object',
    properties: { id: { type: 'string', description: 'The order id' } },
    required: ['id'],
  },
  async execute(args: { id: string }) {
    return `order ${args.id}: shipped`;
  },
};

kortix validate shows what each agent enables. The researcher agent omits most grants, so it gets none of them:

✓  kortix.yaml is valid

What each agent enables:
  support  skills=[refund-policy, kortix-cli]  subagents=[researcher]  commands=[all]  extensions=[web-access]  connectors=[helpdesk]  secrets=[HELPDESK_TOKEN]
  researcher  skills=[none (default-deny)]  subagents=[none (default-deny)]  commands=[none (default-deny)]  extensions=[none (default-deny)]  connectors=[helpdesk]  secrets=[none (default-deny)]

Registries and grants

The project registers what exists. Each agent enables what it uses, by name. A registered item reaches no agent until an agent enables it.

• A grant is all (or *), none (or ""), or a list of names. A list that contains * means all.
• Omitted means none. An omitted skills, subagents, commands, extensions, connectors, secrets, apps or kortix_permissions grants nothing.
• Three keys are open by default: tools is all, permission is allow, and codemode is on.
• workspace.project_repository defaults to false. Set true on every agent that reads or changes the repository, runs its scripts, or opens change requests.
• Names must exist. A listed skill, command, extension, subagent or tool that is not registered or built in is an error.
• Built in, with no entry. The Kortix skills: kortix-cli, kortix-memory and the other kortix-* skills. The Kortix tools: web_search, image_search, image_gen, scrape_webpage, memory, show. See Kortix tools. The built-in tools: bash, read, write, edit, glob, grep, question, task. An agent loads a Kortix skill only when its skills grant names it or is all.
• Only declared agents run. There are no built-in agents.
• Extensions are packages for the agent runtime. A package holds runtime extensions, skills, prompts or themes. The change request merge builds npm packages, and a session never installs them. A session loads its extensions when its runtime starts, so a change reaches a running session at its next start.

Top-level keys

Agent keys

Registry entries

skills entries

tools entries

commands entries

extensions entries

Section keys

env keys

sandbox keys

triggers keys

connectors keys

policy keys

apps keys

Permission rules

agents.<name>.permission decides which tool calls run, wait for a person, or never run. What a person sees when an agent asks is on Agents.

permission:
  bash:
    "*": allow
    "git push *": ask
    "rm -rf *": deny
  edit:
    "*": allow
    "secrets/*": deny
  external_directory: deny
  webfetch: ask

• Value. One action for every tool: allow, ask or deny. Or a map of key → action, or of key → map of glob → action.
• Keys. A capability: read, edit, glob, grep, bash, external_directory, question, webfetch, websearch. Or a tool’s own name, which wins over its capability.
• Tools that follow a capability. write follows edit. memory follows edit, or read when it only views. image_gen follows edit. web_search and image_search follow websearch. scrape_webpage follows webfetch.
• Action only. question, webfetch and websearch take an action, not a glob map.
• bash globs match each command of a line. In a; b, a | b or $(b), the strictest answer wins: deny, then ask, then allow.
• Path globs match the file, relative to /workspace. A path outside /workspace also answers to external_directory. A path rule does not govern bash.
• Precedence. The most specific matching rule wins, whatever the key order. The longest pattern is the most specific.
• permission.skill and permission.task are errors. Use skills and subagents.

Connector rules and approvals

Kortix decides each connector call in this order. In each list, the first rule that matches decides.

1. The project policies.
2. The calling agent’s policy set on that connector (agents.<name>.policy_sets). A set the connector does not define blocks every call of that agent on it.
3. The connector’s own policies, the base rules.
4. No rule matched: a sensitive connector holds the call for approval. Otherwise policy.default_mode decides.

A set or a base rule cannot loosen a project rule. A set can loosen a base rule for its agent.

policy:
  default_mode: risk
policies:
  - match: gmail.send_email
    action: require_approval
    conditions:
      - arg: to
        match: "*@example.com"     # a glob, or /regex/ in slashes
  - match: gmail.send_email
    action: block
approvals:
  ttl: 4h

• An agent policy_sets entry that names a set the connector does not define is an error. An entry for a connector the agent is not granted, or that connectors does not declare, is a warning: it does nothing.
• kortix validate does not check policy or policies. When Kortix syncs connectors, it skips a malformed rule and reports it as a connector sync error.
• A held call that nobody decides within approvals.ttl expires. Approving one is on Connectors.

Sandbox templates

A session picks its sandbox template in this order:

1. The template the session request names.
2. The sandbox of the agent the session runs.
3. sandbox.default.
4. The platform image.

A hardware value below 1 is an error. A value above the maximum is a warning, and Kortix clamps it. gpu is a warning and does nothing. An image key set directly on sandbox (image, dockerfile, slug, cpu, memory, disk, entrypoint, context, context_dir, gpu) is an error: put it in a template.

What each place on the sandbox keeps:

• /workspace holds this session’s files, kept for the life of the session.
• /drives (Drive) holds your files and the company’s files, shared across sessions and kept until deleted.
• Anything else (home directory, /tmp, installed packages) can be gone when the session reopens. Put tools in a sandbox template.

imports

imports splits the manifest across several YAML files. Kortix merges them first. Validation, triggers, grants and connector sync all read the merged manifest.

# kortix.yaml
kortix_version: 3
default_agent: assistant
imports:
  - triggers/          # every .yaml and .yml file below this folder
agents:
  assistant:
    prompt: You write reports.

# triggers/reports/weekly.yaml
triggers:
  - slug: weekly-report
    on:
      cron: "0 0 15 * * 0"
    run:
      agent: assistant
      prompt: Build the weekly report.

1. A path is relative to the repository root. .., an absolute path and a glob are errors. A path that matches no .yaml or .yml file is an error.
2. A folder import takes every .yaml and .yml file below it, at any depth, sorted by path.
3. An imported file holds only agents, apps, commands, connectors, extensions, skills, tools, triggers and imports. Any other key in it is an error.
4. Imports nest up to 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, App slug, skill, tool, command or extension declared in two files is an error that names both files.
6. Entries merge in order: the importing file first, then its imports as listed.
7. A Kortix edit to an entry rewrites the file that declares it. A new entry goes to kortix.yaml.

A broken import fails the whole manifest:

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

Kortix tools

Kortix maintains six tools. A kortix_version: 3 project registers all six with no entry. Every agent gets them unless its tools narrows them. The sandbox runs the same module on both harnesses, with the same name, arguments and output.

• See what a session gets: run kortix tools ls from the project root.
• A kortix_version: 2 project selects Kortix tools under tools: as <name>: kortix:<name>. With no tools: key, in the root file or in any imported file, it gets all six. With a tools: key, even an empty one, it gets the Kortix tools the key lists, plus image_gen. Deleting a line removes that tool from every agent, except image_gen, which loads when its line is missing.
• Own a Kortix tool: kortix tools eject <name> writes the source the sandbox runs to tools/<name>.ts and points the tool at it. The copy imports only node:* modules. web_search, image_search, and scrape_webpage call the Kortix API with KORTIX_API_URL and KORTIX_TOKEN from context.env. image_gen calls the Kortix LLM gateway with KORTIX_LLM_BASE_URL and KORTIX_TOKEN. memory and show work on files in the project checkout. In a v2 project with no tools: key, the eject creates one and also lists the other five Kortix tools as kortix:<name>, so it removes nothing.
• context.turnId is optional in the context a tool’s execute(args, context) receives: the turn the call belongs to, when the harness names it. pi sets it, and it is the same for every call of one turn, also for calls from a codemode script or a subagent. context.signal can differ per call. Key a per-turn limit on turnId. An OpenCode session does not set it.

Generate images

image_gen generates one to four images from prompts, or edits images that are in the workspace. It uses an image model the project can reach: gpt-image-2 on a connected ChatGPT plan, or an image model of an OpenAI, Google, xAI, or OpenRouter key. You can also name a model of your custom endpoint. Kortix-managed models do not generate images yet. It saves each image under /workspace/output/images/.

• One call, one to four images. Each prompt is one image. The tool sends one request per prompt, all at the same time.
• It needs an image model. Connect ChatGPT in Customize → Models (Connect ChatGPT) or with kortix providers login openai, or add an OpenAI, Google, xAI, or OpenRouter key. See Models. With none, the call fails with image_model_unavailable.
• The output is paths, not images. The model receives { action, model, provider, images: [{ path, size, prompt, sha256 }], failed: [{ prompt, error }] }. model and provider name what made the first saved image. size is WxH, read from the saved file when its header is readable, else the size the provider reported. sha256 is the lowercase hex SHA-256 of the saved file’s bytes. failed is present only when a prompt failed. When every prompt fails, the call fails with the first error.

• quality and transparent_background reach ChatGPT and OpenAI models only. Other models do not receive them.
• ChatGPT and OpenAI models receive a size, not a ratio. auto is auto. 1:1 is 1024x1024. 3:2, 4:3, and 16:9 are 1536x1024. 2:3, 3:4, and 9:16 are 1024x1536. xAI models receive no aspect ratio. Other models receive the ratio as it is, and no ratio for auto.
• The file name is a slug of the prompt plus a timestamp. The extension comes from the image bytes: .png, .jpg, or .webp. Any other answer, for example an SVG, is not written.

The image card in the chat

A call shows one card with one frame per prompt.

• While the call runs, the card shows a placeholder per image in the requested aspect ratio, with “Generating image” (or “Generating 3 images”; “Editing image” for an edit) and the elapsed time. The images replace the placeholders when the call ends.
• One image fills the width of the message. Two to four images fill one rectangle: 2 side by side, 3 as one large image and two small ones, 4 as a 2 × 2 grid. On web, the card is at most 60% of the window height.
• The card shows no prompt and no model name. Click an image to open it full screen, uncropped. The full-screen view shows its prompt and the model that made it.
• A frame whose prompt failed shows the error. When the cause is a missing or expired connection, the card shows one connect action. A shared or read-only view shows no action.

Image limits

The tool enforces these limits in code. A prompt, a file, or a web page that the agent reads cannot raise them.

• Every call of one turn counts toward the same 10: direct calls, parallel calls, calls from a codemode script, retried calls, and calls from a subagent the turn started.
• A reference image must be inside /workspace, after symlinks are resolved. Its content must match its extension. Any other file is refused before a request leaves the sandbox.
• An image is always written under /workspace/output/images/. An existing file is never replaced: the tool adds -2, -3, and so on to the name.
• When the turn stops, the requests stop and no further file is written.

Image errors

When the gateway refuses a prompt, its error is Image generation failed (<status>): <message> <suggestion> [<code>]. A rate limit adds Retry after <n> s. before the code. When the gateway names the provider that failed, [provider:<id>] comes right before the code, for example [provider:openai] [provider_reauth_required]. openai-codex is ChatGPT. The tool reports three failures itself: Image generation returned no image., an image that is not png, jpeg, or webp, and its own 300-second timeout. The tool’s timeout starts before the gateway’s, so a slow request usually ends with the tool’s timeout, not image_timeout.

Turn image generation off

Turn image_gen off for one agent with its tools map, or deny it with a permission rule:

agents:
  kortix:
    tools:
      image_gen: false        # the model does not see the tool
  researcher:
    permission:
      image_gen: deny         # the model sees it, every call is denied

• Set image_gen: ask to approve each call.
• image_gen writes a file, so edit: deny also denies it, unless the agent sets a rule for image_gen. The same applies to memory, on both harnesses.
• On OpenCode (deprecated), these tools cannot ask: edit: ask or an edit pattern map denies them.

Replace the image tool

Map image_gen to your own module. The module replaces the Kortix tool on every harness:

tools:
  image_gen: tools/image_gen.ts

kortix tools eject image_gen writes the Kortix source to tools/image_gen.ts and sets this line. Keep the output shape { action, model, provider, images: [{ path, size, prompt, sha256 }], failed }, or the chat shows the raw output in place of the image card. sha256 is optional: outputs from before it was added have none.

Which model makes the image

The image_gen tool and the gateway’s /v1/images/* endpoints use one image model per request. With model set to auto or left out, the gateway tries every image model the request can reach, in this order. Any error moves the request to the next model. A timeout or a stopped request ends it.

1. codex/gpt-image-2, when a ChatGPT account is connected.
2. One model per connected provider, in this order. Each provider uses the first id the model catalog lists as an image model.
   • OpenAI key: gpt-image-1.5, gpt-image-1, gpt-image-1-mini.
   • Google key: gemini-2.5-flash-image, gemini-3.1-flash-image.
   • OpenRouter key: google/gemini-2.5-flash-image, google/gemini-3.1-flash-image.
   • xAI key: grok-imagine-image.

• A disabled provider or model is skipped.
• A named model must be one the model catalog lists with image output. Any other model returns not_an_image_model, with up to 5 image models the project can use. A named model has no fallback.
• Two kinds of models with image output in the catalog do not count: Google Deep Research agents (deep-research-*) and routers that pick a model per request (an id whose last segment is auto, such as openrouter/openrouter/auto).
• Kortix-managed models do not generate images yet. No model in the managed lineup has image output.
• A model of your custom endpoint is tried when you name it, for example my-vllm/flux-dev. auto never picks one. The model must be in the endpoint’s model list; a model missing from it fails with model_not_found. It works when the endpoint answers /chat/completions with the image in choices[0].message.images[0].image_url.url, as a data: URL. Otherwise the call fails with image_upstream_error: the endpoint’s own error, or <model> returned no image.
• The routing policy and the fallback models do not apply to images.
• Kortix calls the model with the protocol of its provider: the OpenAI Images API for ChatGPT, OpenAI, and xAI; Gemini generateContent for a Google key; chat completions with image output for OpenRouter and a custom endpoint. Anthropic and Bedrock models cannot generate images through Kortix.
• A ChatGPT plan sets its own image limit, separate from the plan’s chat limit. Reaching the image limit does not pause the account for chat.

Image costs

• A ChatGPT plan: Kortix charges nothing. The image counts against the plan’s image limit.
• A custom endpoint: Kortix charges nothing.
• Your own key: your provider bills the image. Kortix applies the same rule as for chat on your own key: see Models.
• Kortix charges only for a delivered image. A refusal, an answer without an image, a timeout, or a stopped request records no Kortix charge, and any credit hold is returned.

Image endpoints on the gateway

A gateway key (kortix_gw_…) also calls the image endpoints:

Both take { model, prompt, aspect_ratio, quality, background, images }. model defaults to auto. images is for edits only: [{ "image_url": "data:image/png;base64,..." }]. The gateway makes one image per request and drops every other field. A legacy size (1024x1024, 1536x1024, 1024x1536) is read as the matching ratio when aspect_ratio is absent. The answer is { created, model, provider, data: [{ b64_json, mime_type }], size, usage } for every provider. size and usage are present when the provider reports them.

Migrate to v3

A project created in Kortix starts on kortix_version: 3. Projects on kortix_version: 1 (kortix.toml) or kortix_version: 2 keep running unchanged. Upgrading is opt-in, and it lands as a change request.

From Kortix. Select the upgrade alert in the project sidebar. Or open Customize → Settings → Upgrades and select Run on Upgrade manifest to v3 (kortix.yaml). The alert shows only to people who can write to the project. Or run:

kortix projects upgrade [<id>]

Each one starts a session with the project’s default agent. The agent converts the manifest with kortix migrate, runs kortix validate and opens a change request. It never merges it: a person reviews and merges it. Starting the upgrade needs permission to start sessions in the project.

By hand. In a checkout of a v1 or v2 project:

kortix migrate            # preview: the plan and the new kortix.yaml; nothing changes
kortix migrate --write    # apply it
kortix validate

kortix migrate does this:

• From v1, each [[agents]] entry and each agent .md becomes an agent. A grant v1 omitted is written as all, because v1 meant all. env becomes secrets. default_agent comes from the old harness config, else the first agent. kortix.toml is deleted.
• It moves each agent’s .md frontmatter into its block. The .md keeps the prompt alone and becomes prompt_file.
• It copies the project-wide permission of the old harness config onto every agent that sets none, and deletes that config file.
• It turns permission.task into subagents.
• It turns the skills/<name>/ folders into the skills registry.
• It turns the harness folder’s command files into the commands registry. Each command is enabled on the agent its frontmatter names, else on default_agent.
• It turns plugins and harnesses.pi.packages into extensions, enabled on every agent that loaded them, and harnesses.pi.codemode into codemode.
• It sets workspace: { project_repository: true } on every agent that had the repository, because v3 defaults to false.
• It keeps a split manifest split. Each entry stays in its file, and the new registries go to kortix.yaml.

It lists what it cannot carry over under Not carried over. It refuses to write a result that does not validate. --json prints the plan as JSON. Then commit, push, and open a change request.

What changes from v1 and v2:

CLI

kortix is the Kortix command line. It does from a terminal what the web app does: create and clone projects, run sessions, review change requests, and configure agents, connectors and secrets. Use it on your own machine, in CI, from a coding agent, and inside a session sandbox, where it is already installed and signed in.

curl -fsSL https://kortix.com/install | bash
kortix login
kortix --help

Install

The install script supports macOS and Linux on x86_64 and arm64. On Windows, run it inside WSL. It does these steps:

1. Downloads the release binary for your system from GitHub Releases.
2. Checks it against the release’s SHA256SUMS. A missing or wrong checksum stops the install. When cosign is installed, it also checks the Sigstore signature of SHA256SUMS.
3. Puts the binary in ~/.kortix/kortix.
4. Links kortix and kortixt (the TUI) into /usr/local/bin. If that directory is not writable, it uses ~/.local/bin when it exists, else sudo.

curl -fsSL https://kortix.com/install | KORTIX_VERSION=0.14.8 bash

Check the install with kortix version. To update or remove the CLI, see Maintain the CLI.

Sign in to a host

kortix login

The CLI signs in to one Kortix instance at a time. An instance is a host. The order is always host › account › project › session.

You sign in to a host and pick an account in it. Then you pick a project in that account and run sessions in it.

kortix login does these steps:

1. Opens your browser. You approve the CLI there, and the token comes back on a local callback.
2. Selects your account. With one account it picks it. With several it asks. --account <slug> skips the question.
3. Sets a default project for the host. --no-project skips this step.

To create a token for --token, see Security.

Hosts

Every host keeps its own login. You use these two built-in hosts:

The CLI changes a remote http:// URL to https://. A private address keeps http://: localhost, a LAN IP, and a name that ends in .local, .lan, .internal or .home.arpa. A name with no dot, such as a Docker Compose service, also keeps it.

The logins live in ~/.config/kortix/config.json, with file mode 0600. KORTIX_CONFIG_FILE sets another path.

Check who you are

Which project a command uses

A project command runs against the first project it finds in this order:

1. --project <id> on the command.
2. .kortix/link.json in the current directory. The CLI does not look in parent directories.
3. The KORTIX_PROJECT_ID environment variable.
4. The host’s default project.

kortix projects use also switches the active account to the project’s account. kortix projects link writes .kortix/link.json and works only in a directory that has a .kortix/ directory or a kortix.yaml. kortix projects clone and the first kortix ship write the link for you.

The link also records the host. A command in a linked directory goes to that host, whatever host is active.

A session ID works across projects. When the session is not in the resolved project, the CLI searches your other accounts and logged-in hosts. --host or --project turns the search off. The 8-character short ID from kortix sessions ls works anywhere a session ID goes.

The everyday loop

The loop runs on the project’s git repository. You push your branch, each session works on its own branch, and you merge its change request. Quickstart walks through it the first time. Git covers cloning, pushing from any git client, session branches and change requests.

kortix init my-agent && cd my-agent           # new project from the starter
kortix ship                                   # validate, commit, push; creates the project
kortix sessions new --prompt "Add a skill that drafts the weekly status report"
kortix chat <session_id>                      # talk to the agent; -p "…" sends one prompt
kortix sessions wait-for <session_id>         # block until the agent is done
kortix cr ls && kortix cr diff 1              # read its change request
kortix cr merge 1 && git pull                 # merge it and pull the result

• kortix init writes a kortix_version: 3 project. Its fields are on kortix.yaml reference.
• kortix projects clone <project_id> my-agent gets an existing project instead. It clones with your Kortix login and installs a git credential helper, so plain git pull and git push work in the clone.
• kortix ship commits every change (git add -A) and asks for missing secrets. Then it pushes the current branch to the branch with the same name and asks you to connect declared connectors. kortix deploy is the same command.
• 1 is the change request number from kortix cr ls. kortix cr request-changes 1 --message "…" sends the note to the session that opened it.

Run in CI and scripts

Give the job a token in the environment. The CLI then needs no kortix login:

KORTIX_TOKEN outranks any stored login, and the CLI never writes it to disk. Create a key that can reach only one project:

kortix tokens new ci-nightly --project <project_id> --expires 90d

The key prints once. Store it in your CI secret store. --expires takes an ISO-8601 date or a span such as 30d, 12h, 6w or 1y.

# .github/workflows/nightly-report.yml
name: Nightly report
on:
  schedule:
    - cron: "0 6 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    env:
      KORTIX_TOKEN: ${{ secrets.KORTIX_TOKEN }}
      KORTIX_PROJECT_ID: ${{ vars.KORTIX_PROJECT_ID }}
    steps:
      - run: curl -fsSL https://kortix.com/install | bash
      - run: |
          id=$(kortix sessions new --prompt "Write the nightly report" --wait --json | jq -r .session_id)
          kortix sessions wait-for "$id" --timeout 1800
          kortix sessions log "$id" --limit 1

Pipe --json output into jq. Update checks are off when CI is set or stdout is not a terminal. To start sessions on a schedule inside Kortix itself, use Automations.

Use Kortix from your coding agent

A coding agent such as Claude Code, Codex, Cursor or pi needs only the binary, a login and the platform manual.

kortix doctor

kortix system-skills get kortix-system

kortix init --force

id=$(kortix sessions new --prompt "Fix the failing export test" --wait --json | jq -r .session_id)
kortix sessions wait-for "$id" --timeout 900
case $? in
  0) kortix sessions log "$id" ;;
  3) kortix sessions pending "$id" ;;
esac

An MCP client can use Kortix without the CLI. See Everywhere.

Inside a session sandbox

Every sandbox has the CLI installed and signed in. The platform sets KORTIX_TOKEN, KORTIX_API_URL and KORTIX_PROJECT_ID, so the agent runs commands with no login and no link. The token is a session token: kortix token shows its session, its agent and its grants. It acts only on the session’s own project.

Commands an agent uses:

What an agent may do is set by its kortix_permissions in kortix.yaml. When the API refuses a command, the CLI prints the token kind, the agent and its grant. See Agents. These commands are refused for an agent session’s token, whatever the grant:

• kortix projects cli-tokens new and rm
• kortix gateway keys (ls, new, rm)

kortix update is refused in a sandbox. The platform manages the binary: restart the session to get the current CLI.

A .kortix/link.json for another project needs a stored login for that project’s host. Run kortix login in the sandbox first.

Command reference

Every command prints its subcommands and flags with kortix <command> --help, or kortix help <command>. A command that belongs to a feature that is off for the project is not listed in kortix --help.

Start here

Sign in, per host

Account, within the host

Project, within the account

Session, within the project

Author and ship

Agents and connectors

Files, changes and triggers

Access and permissions

The CLI itself

Session commands

The commands below are kortix sessions <subcommand>. kortix sessions --help lists every flag. The behavior behind them is on Computers.

Start and list

Talk

Watch

Unblock

Files and ports

Lifecycle

Access

Check and validate

The schema fields are on kortix.yaml reference.

Conventions

• kortix, kortix help and kortix --help print the same screen: your host, account and project, then every command. kortix help <command> prints that command’s help.
• --host <name> sends one command to another host. --project <id> sends it to another project. Both also work before the command: kortix --host <name> sessions ls.
• --json, on a command that supports it, prints JSON. On any command it turns off the host and update notices, also on stderr.
• --debug prints the resolved host, account and credential source to stderr.
• A mistyped command exits 2 and, when a command name is within two edits, prints it as a suggestion. It never scaffolds a project directory. Only kortix init does that.

Maintain the CLI

The bare kortix command checks for a new release at most every 6 hours and offers to install it. Other commands show a one-line notice from the cached check. Turn the check off with KORTIX_NO_UPDATE_CHECK=1. Keep the notice but skip the question with KORTIX_NO_UPDATE_PROMPT=1.

kortix uninstall asks before it removes anything:

kortix feedback takes --kind bug|idea|friction (default idea). Inside a session it tags the report with the session and project IDs.

REST API

The Kortix REST API is the HTTP interface to accounts, projects, sessions, secrets, connectors, triggers, and Apps. The web app, the CLI, the SDK, and the Kortix MCP server all call it. Use it directly from any language that can send an HTTPS request with a bearer token.

The shortest path: create a personal access key, list your projects, and start a session.

kortix tokens new my-script --expires 30d    # prints kortix_pat_… once
export TOKEN=kortix_pat_...

curl -s https://api.kortix.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"

curl -s https://api.kortix.com/v1/projects/<project_id>/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"initial_prompt": "Summarize the open change requests."}'

GET /v1/projects returns an array of projects, each with project_id. The session create returns 201 with the session, including session_id and branch_name. It returns 202 with status, command_id, and session_id when Kortix queues the create. Read the session with GET /v1/projects/<project_id>/sessions/<session_id> until it appears.

With only a session_id, GET /v1/sessions/<session_id> returns the same session with its project_id. The access rules are the same.

A session you cannot read, an unknown id, and a deleted session all return 404. A session in an account or project you have no access to also returns 404, so the id alone never shows that a session exists. A key scoped to one project cannot call it. Use the project route with that key.

Pick a surface

All four surfaces reach the same API with the same permissions.

Prefer the SDK for anything that drives a session. It owns the start, the readiness wait, the event stream, and the runtime routes. The REST reference does not list those routes.

Base URL and reference

Every deployment serves its own route reference:

• GET /v1/docs: the interactive reference. The API reference tab at the top of these docs opens the Kortix Cloud copy.
• GET /v1/openapi.json: the OpenAPI 3.1 document. Its servers entry is the origin you requested it from, so a client generated from a self-hosted instance points at that instance.
• GET /v1/health: no token needed. Returns status, service, version, commit, environment, timestamp, and started_at.

The reference leaves out operator routes. A self-host operator turns off both /v1/docs and /v1/openapi.json with OPENAPI_PUBLIC_DOCS=false in the API environment.

Authenticate

Send one header on every request:

Authorization: Bearer <token>

The token decides who the request acts as. Every Kortix credential starts with a prefix that names its kind. Create and manage them on Security.

An OAuth token without the kortix scope reaches only /v1/accounts/me, /v1/oauth/userinfo, and /v1/oauth/revoke. Other routes answer 403, and message starts with insufficient_scope. Even with the kortix scope, an OAuth token cannot change sign-in, password or MFA state. It also cannot create a credential that outlives the grant, or request account deletion.

A person’s access token from headless sign-in also works as a bearer token. It acts as that person.

A missing or invalid token returns 401. A 401 with code: "session_token_revoked" means the credential is revoked, expired, or belongs to a closed session. It never works again: stop retrying and get a new token.

The same tokens open the project’s git origin. See Git.

Errors

An error response is JSON. Every body has error. The generic shape adds message and status. A typed error adds code and can add more fields.

Some errors add fields. A failed body, query, or path validation returns:

{ "error": true, "message": "Validation failed", "status": 400, "issues": [ … ] }

issues lists each invalid field with its path and message.

Every response carries an X-Request-Id header. Quote it when you report a problem.

Common error codes

These are the codes clients branch on most. The linked section explains each fix.

A connector call reports its outcome in reason, not code, inside { ok: false, status: "denied" | "error", reason }. The reasons, such as connector_not_connected and policy_block, are on Connectors. LLM provider and model failures are on Models.

Retries and idempotency

The SDK retries reads, and a DELETE that got no response. It never repeats any other write. In your own client, decide per response:

Idempotency-Key

Two create routes deduplicate a retried request:

Send a new random value, such as a UUID, for each intent. Send the same value again when you retry that intent. A repeated session create returns the original session instead of starting a second sandbox.

Session keys are unique across all of Kortix. A key that another project or account already used returns 409 IDEMPOTENCY_KEY_CONFLICT.

Pagination

A list route that pages takes limit and cursor. Pass the next cursor back as cursor. No next cursor means you have the last page.

A session page holds only the sessions you may open. Every page except the last holds exactly limit sessions. A delete does not move a session in the list order.

The session list also returns an ETag. Send it back as If-None-Match and an unchanged list answers 304 with no body.

Rate limits

A rate-limited route returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the window resets). When the limit is reached it returns 429 with Retry-After and this body:

{ "error": "rate_limit_exceeded", "message": "Rate limit exceeded. Please retry shortly.", "retry_after_seconds": 12 }

What the reference does not cover

The reference does not list the session runtime routes. The surfaces below also take a different credential or protocol than a plain bearer call:

Machine-readable docs

These docs are also published as plain Markdown for coding agents and LLM tools:

Point a coding agent at https://kortix.com/llms.txt for the concepts and at https://api.kortix.com/v1/openapi.json for the exact routes. An MCP client that uses the Kortix MCP server reads the route reference itself through search_api and describe_api.

Apps reference

An App is a deployment that one project owns. It has one stable URL, an access policy and numbered releases. Use Apps to host a site, an internal tool or a backend for the people in your project. Kortix signs them in before your code runs.

What an App is

An App is either static or a server. A static App is files that Kortix serves itself, with no machine. A server App runs machines that Kortix builds from your source or image.

A database, a queue or any other backend is a server App with a volume. A template writes a ready-made App for you: see Template: Convex backend.

Every App lists what it supports in capabilities, for example machines or volumes. A call that needs a missing capability answers 409 app_capability_unsupported.

Show an App hosted elsewhere

An external App is a site that runs somewhere else: a dashboard, a vendor tool, another team’s service. Kortix lists it in the Apps page beside the Apps it runs and opens it in place, in a frame. Kortix never deploys, wakes or bills it, and it takes no App slot.

Add one from the Apps page with Add app, or from the CLI:

kortix apps create grafana --name "Grafana" --url https://grafana.example.com

• The URL must be https. A URL with a user name or password is refused.
• The App’s url and external_url are the site. capabilities is ["preview"].
• The site decides whether it may be framed. Kortix reads its X-Frame-Options and CSP frame-ancestors headers when you add it. A site that refuses a frame gets capabilities: [] and the warning app_external_not_frameable. Kortix then shows it with an Open in a new tab control instead of a frame.
• A site that keeps its sign-in in a cookie can ask you to sign in again inside the frame. Browsers limit cookies in frames from another site. Open it in a new tab when that happens.
• The access policy decides who in the project sees the App. The site’s own sign-in decides who can use it.
• Move it to another URL with kortix apps set grafana --url <https-url>. Deploy, rollback, start, stop and sign-in tokens answer 409 app_capability_unsupported.

Self-hosting prerequisites

Every project can create and deploy Apps. On a self-hosted instance, App hostnames resolve only after the operator sets an Apps base domain and its wildcard DNS record: see Self-hosting.

Deploy your first App

npm run build

kortix apps deploy dist --slug my-site --type static --spa

kortix apps access-link my-site

npm run build && kortix apps deploy dist --app my-site

The web app lists every App you may open at Apps in the project sidebar (/projects/<id>/apps). The page shows live state, a preview and the access controls. An App’s detail lists its releases.

A server App adds a Machines tab, and an App with a volume adds a Volumes tab. ?app=<app_id> opens one App’s detail. You create and deploy Apps from the CLI, the SDK or an agent session.

Sources

• Pick static for every UI you can build ahead of time. Build locally and deploy the output. A Next.js site with output: 'export' deploys out/ as static.
• Pick dockerfile for server rendering, native packages or any service.
• dockerfile and oci_image need --command (a JSON argv array is unambiguous) and --port, or http_service.internal_port in kortix.yaml. A worker-only App (processes and no service) needs no port.

For a directory, the CLI picks the source when you omit --type: a Dockerfile makes it dockerfile, else a package.json makes it bundle, else static. The defaults:

What the CLI uploads:

• It honors .gitignore, .dockerignore and .kortixignore.
• It never uploads .git/, .kortix/ or .env*. It leaves out node_modules unless you pass --include-node-modules.
• A build-time value, such as VITE_* in .env.production, reaches a static App only through a build you run before the deploy.

Limits:

A static App runs no code, so it ignores env and secrets. A deploy that sets them records an environment_ignored event.

A deployment moves through queued, validating, building, provisioning, checking and ready, or ends failed or cancelled. kortix apps deploy waits up to --wait-seconds (default 1200). --no-wait returns once the deployment is queued.

Configure in kortix.yaml

An apps.<slug> block in kortix.yaml holds an App’s deploy settings and release config. Commit it, and every deploy uses the same settings.

apps:
  docs:
    path: docs/dist
    type: static
    spa: true
  api:
    path: services/api
    type: dockerfile
    command: ["node", "server.js"]
    labels: [backend]
    display: { preview: none }     # an icon card, not a live thumbnail
    always_on: true
    uses: [docs]
    processes:
      app: ""                      # "" runs the block's command
      worker: "node worker.js"     # no service names it: a worker
    http_service:
      internal_port: 3000
      access: app                  # public | app | admins
      processes: [app]
      checks: [{ type: http, path: /health }]
    services:
      - { name: admin, internal_port: 3001, access: admins }
    mounts:
      - { source: data, destination: /data, initial_size_gb: 10, processes: [app] }
    vm:
      - { cpu: 1, memory_gb: 2 }
      - { cpu: 1, memory_gb: 1, processes: [worker] }
    deploy:
      release_command: "node migrate.js"
    env:
      PUBLIC_BASE_URL: https://example.com
    secrets:
      API_TOKEN: api_token         # runtime name: project secret identifier