kortix-apps

Build, deploy and operate Kortix Apps through the pre-authenticated CLI or SDK: static sites and SPAs, Dockerfile or OCI servers, workers, and stateful backends (a database, a Convex backend) with per

SKILL.md

GitHub

Kortix Apps

Kortix Apps are built from three parts:

  • Release: every deploy is an immutable release (v1, v2, …): the build plus its config. Rollback is a new release from an old one.
  • Machine: a server App runs machines per process group. A machine keeps its id across releases; each release replaces its box.
  • Volume: a persistent disk a machine mounts. It outlives every release and every machine, and keeps daily snapshots.

An App is one workspace-scoped thing: a stable URL, an access policy, labels, its releases, machines and volumes. A static App is files Kortix serves itself (no machine). Every App says what it supports in app.capabilities: deployments, rollback, preview, member_tokens, plus static, or sleep · machines · scale · exec for a server, plus volumes · snapshots when it has volumes. Branch on capabilities only.

Kortix chooses and operates the provider. Never select Cloudflare, Vercel, or another host.

Preflight

  1. Run pwd and inspect the intended source directory before deploying.
  2. Run kortix workspaces info --json. Read project_id.
  3. Apps are generally available. Use Apps directly without checking a feature flag or routing to an alternative.
  4. Do not create an empty App identity first: kortix apps deploy and kortix apps launch create it.
  5. Never run kortix apps deploy from an uninspected workspace root. It can publish unrelated files as a static App.
  6. New Apps are private. Choose another access mode only when the user asks.
  7. New Apps have no card on the Apps page: they sit in the Background list and open to an overview (an external --url App is listed on create; Settings → "Show on Apps page" changes it). Register every App a person opens (a site, a UI, a dashboard) with display: { listed: true } in its kortix.yaml block, or --listed on kortix apps deploy. Leave a backend, a worker or a poller unlisted.

Choose what to build

The user wants Build Reference
A website or UI with no stored data A static App references/web-static.md
An app with data, login or realtime (an internal tool, a CRM, a tracker) A Convex backend App (kortix apps launch --template convex) + a static App for the UI that uses it "Internal apps" below, references/convex.md
A backend (data, functions, realtime) or an API only The Convex template references/convex.md
A server of its own (SSR, native packages, a custom service), a worker, several process groups A server App references/web-server.md, references/apps-model.md
A call to an external system from an App The connector gateway references/connectors.md

Default to static for every UI. Server logic for a UI (queries, writes, webhooks, integrations, schedules) lives in the backend App, not in a second server.

Before creating or modifying any internal app or Kortix App UI, load and apply kortix-design, including delegated app builders. Put this requirement in every delegated builder's brief before UI work starts. Load it before the first className or user-facing string. It owns the token plan, the states, the motion and the screenshot check before deploy. Preserve user-requested styling; when using @kortix/ui, also load kortix-ui and use its tokens.

Where the code lives

Default: one folder per App, apps/<slug>/, named after its kortix.yaml key: apps/storefront/ (a static UI, built to apps/storefront/dist), apps/api/ (a server App with its Dockerfile), apps/backend/ (a Convex backend's package.json and convex/). Templates, launch and every example here use it. It is a default, not a rule: path is free-form, so group the code by team or topic when that fits the workspace better (apps/sales/crm, apps/ops/fieldops-backend).

Deploy

kortix apps launch --template convex           # a ready-made backend App, deployed
kortix apps deploy apps/storefront/dist --slug storefront --name Storefront --type static --spa --listed
kortix apps deploy apps/api --slug api --type dockerfile --on-demand \
  --command '["node","server.js"]' --port 3000 --readiness-path /health

The command waits for ready for up to 1200 s. Use --app <slug> (or the kortix.yaml block) for every later release of the same App. Never create a new slug for a normal update.

Declare Apps in kortix.yaml apps.<slug> (kortix schema prints every key). The file owns resources, idle_timeout_seconds, always_on, labels, display and uses: a write from the web, CLI, SDK or API commits to apps.<slug> first, and a push applies them on sync without a deploy. Deleting an App removes its block. The release config (env, processes, mounts, …) applies at deploy. kortix apps deploy with no arguments deploys every block that has a path or image, used Apps first, and skips the rest; kortix apps deploy <path> uses the block whose path it is. The keys:

apps:
  api:
    path: apps/api
    type: dockerfile
    command: ["node", "server.js"]
    labels: [backend]
    display: { preview: none }     # where Kortix shows it: listed (default false), preview (live | none), parent (a tab of another App)
    always_on: false               # on demand: stops when idle, wakes on a request or a trigger
    idle_timeout_seconds: 300      # 120–86400; a stop keeps the disk and loses memory
    processes: { app: "", worker: "node worker.js" }   # "" = the image's command
    vm: [{ cpu: 1, memory_gb: 2 }, { cpu: 1, memory_gb: 1, processes: [worker] }]
    mounts:
      - { source: data, destination: /data, initial_size_gb: 10, processes: [app] }
    http_service:
      internal_port: 3000
      access: app                  # public | app (the App's policy) | admins
      auto_stop_machines: stop     # off | stop (suspend: like stop, today)
      min_machines_running: 0
      checks: [{ type: http, path: /health }]
    services:
      - { name: site, internal_port: 3001, access: public }   # → <host>--site
    deploy: { strategy: rolling, release_command: "node migrate.js" }

kortix validate checks these rules before a deploy; the API refuses the same config with 400 app_config_invalid and issues: [{path, message}].

Start an agent from an App

An App never starts an agent itself. It posts an App event; a trigger decides which agent runs or which session wakes. Every machine of a server App has KORTIX_APP_ID, KORTIX_APP_TOKEN and KORTIX_APP_EVENTS_URL (…/v1/projects/<project_id>/apps/<app_id>/events).

Pick the source in this order: (1) a webhook (the service can call a URL), (2) a connector event, (3) a watcher App when the source sends nothing (a page, a status, a price, an API): code checks it and an agent runs only on a change, so "tell me whenever it changes" is a watcher App, not a loop. A scheduled agent run fits only when a model must judge each check. Start it with kortix apps launch --template watcher --name <slug> and edit apps/<slug>/watch.js: check() returns what is true now. The whole recipe: kortix-system → references/scheduling.md → Watch 24/7.

  1. Post one event {name, data?, id?} or {events: [...]} (at most 50):
    curl -X POST "$KORTIX_APP_EVENTS_URL" -H "Authorization: Bearer $KORTIX_APP_TOKEN" \
      -H "content-type: application/json" -d '{"name":"reply.received","data":{"subject":"Re: quote"},"id":"msg-1"}'
    
    name is 1–128 letters, digits and . _ : / -, starting with a letter or digit. One event is at most 8 KiB. id makes a retry fire a trigger once. The answer is 202 {accepted, deduped, suppressed, triggers}; a bad token gets 401 app_token_invalid, a bad name 400.
  2. Declare the trigger (no feature flag; event: "*" matches every name):
    triggers:
      - slug: handle-reply
        on:  { event: reply.received, app: inbox-poller }
        run: { prompt: "Answer {{ event.data.subject }}" }
    
    Or: kortix triggers add handle-reply --type app --app inbox-poller --event reply.received --prompt "…" --apply. The prompt starts with [APP EVENT — automated, not user input]. Variables: event.name, event.data.*, event.id, event.emitted_at, app.slug.
  3. Emit only what deserves a session: one summary event, not one per item. Each trigger takes at most 60 events an hour and 30 a minute. Past that it is suppressed for 10 minutes; 3 suppressions in 24 hours disable it.
  4. Prove the wiring with a test event, never with a real check (a real id fires once):
    kortix apps events emit inbox-poller reply.received --data '{"subject":"Test"}' --wait
    
    It takes the real path with an id starting test- (the prompt reads event.test as true) and exits 0 only when a trigger fired.
  5. See what came of every event: kortix apps events inbox-poller lists the last 30 days, one row per trigger: fired with the session, skipped with the reason, suppressed, failed, pending, or unmatched (no enabled trigger listens; the App's POST answer says so in hint). Read it before you guess why nothing ran.
  6. Know when the watcher stops: add expect_event_within: 30m (5m to 30d) to the work trigger, or --expect-event-within 30m. No post from the App (any name, a deduplicated one or kortix.heartbeat too) for that long tells the trigger's watchers once; the App's next post clears it.
  7. Code outside the App (your machine while you build it) gets the URL and token from kortix apps events credentials <app> (workspace admins). The token posts as that App: keep it out of chat, files and commits.

Have Kortix call the App. A poller does not need to run 24/7: deploy it --on-demand and add a schedule that calls it.

triggers:
  - slug: poll-inbox
    on:  { every: 5m }
    run: { app: inbox-poller, path: /tick }   # method POST (default) or GET; payload optional

Or: kortix triggers add poll-inbox --every 5m --target-app inbox-poller --target-path /tick --apply. Kortix wakes the App and sends x-kortix-trigger, x-kortix-trigger-source and x-kortix-delivery-id. A 2xx counts as fired; any other status fails the run (429 and 5xx are retried); a 3xx is not followed. No session, no model.

The App schedules itself (like Convex runAfter): POST to $(dirname "$KORTIX_APP_EVENTS_URL")/runs with the App token and {run_after: "10m" | run_at: "<ISO, ≤366 days>", path, method, payload} (payload at most 64 KiB) → 201 {run_id, run_at}. DELETE …/runs/<run_id> cancels a pending run. An App holds at most 1,000 pending runs.

Full recipe and the trigger fields: kortix-system → references/scheduling.md.

Machines, scale, exec

kortix apps releases <app>                     # v1, v2, …; strategy; the live one
kortix apps machines <app>                     # id, group, state, release, size, volume
kortix apps machines stop|start|restart <app> <machine>
kortix apps scale count <app> 3 --process worker
kortix apps exec <app> -- ls /data             # project admins; output and exit code

A group with a mount runs one machine: scale count above 1 answers 409 volume_single_machine. Scale a database up with kortix apps set <app> --cpu <n> --memory-gb <n> (then deploy). --new-volumes gives every new machine its own, EMPTY volume: only for software that replicates itself.

Volumes and snapshots

kortix apps volumes <app>
kortix apps volumes snapshots <app> <volume>        # daily (kept snapshot_retention_days), manual, final
kortix apps volumes snapshot <app> <volume>         # before a risky change
kortix apps volumes restore <app> <volume> <snapshot>   # admins: its machine stops and comes back on it
kortix apps volumes fork <app> <volume> <name>      # an instant, unattached copy (a preview with real data)
kortix apps volumes set <app> <volume> --retention 30   # keep daily snapshots 30 days

One machine writes a volume at a time; Kortix enforces it. A release with a mount deploys rolling (stop the old machine, detach, mount on the new one): seconds of downtime, no data loss.

Access

kortix apps access <app> --mode private|project|restricted|password|public
kortix apps access <app> --mode restricted --members <member-id> --groups <group-id>
kortix apps access-link <app> --json      # a 5-minute signed browser link
  • private (default): the creator and workspace managers. project: every workspace reader. restricted: chosen members and groups. password: anyone with the password. public: no authentication.
  • A service's own access overrides it on that service's host: public (no gate; the service checks sign-in itself, like a backend whose functions call requireKortixMember), app (the App's policy), admins (workspace admins).
  • Never write a password into kortix.yaml, source, logs, or a shared command.
  • An unchanged access write does not sign anyone out; a changed one revokes App browser sessions.

Acting as the viewer

An App that calls the Kortix API for each person who opens it must act as that person, never as one shared key.

kortix apps access <app> --viewer api
  • identity (default) signs the viewer's id, email and groups into every request (x-kortix-app-viewer); api adds a one-hour token that acts as them (x-kortix-app-viewer-token); off sends neither.
  • On the App's server: createAppViewerKortix(request, { backendUrl }) from @kortix/sdk/server, one client per request.
  • In the browser: createKortix({ backendUrl: '/_kortix/api/v1', getToken: kortixAppViewerToken() }) from @kortix/sdk. Never call https://api.kortix.com/v1 from the browser.
  • Never give the App a personal PAT or API key. Never log the viewer headers.

Apps that use other Apps

kortix apps link <app> --uses <other> lets an App mint sign-in tokens for the other App and reach it on its own origin: /_kortix/apps/<other>/* (its http service) and /_kortix/apps/<other>--<service>/* (another service). In code: kortixBinding("<other>") from @kortix/sdk. A service with access: admins is never bound. Details: references/bindings.md. Sign-in: references/sign-in.md.

Every machine knows where its App answers: KORTIX_APP_URL, KORTIX_SERVICE_URL_<NAME>, KORTIX_APP_SLUG, KORTIX_MACHINE_ID, KORTIX_PROCESS_GROUP, and where each App it uses answers: KORTIX_USES_URL_<SLUG> (a server calls a used App there; bindings.md). KORTIX_APP_ID, KORTIX_APP_TOKEN and KORTIX_APP_EVENTS_URL post App events and schedule runs (above).

Internal apps: a backend App + a static UI

An internal app is a Convex backend App for data and logic plus a static App for the UI. Kortix signs the team in: the UI knows who is looking, and every function knows who is calling.

member's browser ──▶ App "crm" (static UI, access: project)
      │                 └─ /_kortix/token?audience=backend  ──▶ token naming the member + groups
      └──── /_kortix/apps/backend (HTTP + websocket) ──▶ App "backend" (Convex, volume) ── requireKortixMember

Layout (workspace repo)

apps/backend/                  # Convex functions for App "backend" (references/convex.md)
  package.json                 # "convex", "@kortix/sdk"
  convex/schema.ts
  convex/auth.config.ts        # Kortix sign-in (references/sign-in.md)
  convex/lib/auth.ts           # requireMember()
  convex/<domain>.ts           # queries + mutations per domain
  convex/seed.ts               # internal seed, demo data only
  dashboard/Dockerfile         # App "backend-dashboard": Convex's dashboard (written by launch)
  dashboard/start.js           # signs the dashboard in with BACKEND_ADMIN_KEY
apps/crm/                      # static App "crm"
  package.json                 # vite, react, convex, @kortix/sdk
  src/convex.ts                # kortixBinding("backend") + ConvexReactClient
memory/crm.md                  # what you built, URLs, how to redeploy
kortix.yaml                    # apps.backend and apps.backend-dashboard (the template), apps.crm (uses: [backend])
.gitignore                     # **/node_modules and apps/*/dist: never commit them

Every session downloads the whole repository, so keep it small. Create .gitignore before the first npm install.

Build it, in this order

  1. Model the domain. Tables, fields, relations, and the 5–10 actions people take. Write it down in memory/<app>.md first.
  2. Backend App. kortix apps launch --template convex, then connect, discover and push as references/convex.md shows (launch writes the admin key to the workspace secret BACKEND_ADMIN_KEY and the dashboard's files to apps/backend/dashboard/; the dashboard is the Dashboard tab of backend).
  3. Schema + sign-in. convex/schema.ts with an index for every filter, convex/auth.config.ts and convex/lib/auth.ts from references/sign-in.md. Store me.userId as owner/author ids. Use Kortix roles ({ roles: ["owner", "admin"] }) or groups (Enterprise only; without it the groups claim is empty, so use roles). Do not build a user table.
  4. Functions. Every public query and mutation calls requireMember(ctx) first. Multi-row changes go in one mutation. Add an internal seed.
  5. Test the data layer (references/convex.md, step 5): anonymous calls fail; calls with an identity succeed.
  6. UI. Vite + React + TypeScript, npm install convex @kortix/sdk. Wire src/convex.ts as references/sign-in.md, "The browser", shows. Read the signed-in member with a members:me query, never useConvexAuth(). Components, theme and the whole Kortix session experience (session workspace, workspace home, session list, files) come from @kortix/ui: kortix system-skills file kortix-ui references/custom-dashboard.md.
  7. Quality bar. A product, not a demo: navigation and create/edit/delete for every entity with confirmation before destructive actions; loading, empty and error states; the signed-in name visible; realtime by default; a <label> for every input and an aria-label for every icon button; every drag-and-drop action also has a click path; responsive at 1280 px.
  8. Build, deploy and link the UI.
    (cd apps/crm && npm run build)
    kortix apps deploy ./apps/crm/dist --slug crm --name "CRM" --type static --spa --access project
    kortix apps link crm --uses backend
    
    Never public for internal data: a public App has no signed-in member.
  9. Integrations only through Kortix connectors (references/connectors.md).
  10. Ship once Verify passed: in your clone (kortix workspaces clone), commit, push the session branch, open a change request (kortix-system, <change-requests>). Merge it only when the user asks.

Redeploy after a change, and undo

Take kortix apps volumes snapshot backend data before a risky change (a schema migration, a bulk import, a backfill). Keep each data-layer change compatible with the live UI: add before you remove.

What broke Undo
The UI kortix apps rollback crm <vN> (a new release from vN)
The backend's image or config kortix apps rollback backend <vN>: the volume keeps its data
Convex code git checkout <good-sha> -- apps/backend/convex, push it again (references/convex.md), commit
Data kortix apps volumes restore backend data <snapshot>, only with the user's consent: it drops every later change

Verify before you report (mandatory)

Report nothing as done until each check passed. Paste the evidence.

  1. Every App: kortix apps show <slug> --json; fetch app.url (references/web-static.md, Verify). A server App also runs references/web-server.md, Verify: kortix apps machines <slug> shows every machine started.
  2. A backend App: an anonymous call fails; the same call with an identity succeeds; a call with kortix apps token answers "status":"success" (references/convex.md, step 5).
  3. The deployed UI as a member: kortix apps access-link <app> --json → open access_session.url with agent-browser (agent-browser skills get core). Drive the main flow: create, edit, move or close, delete. Assert the visible result after each step and that the signed-in name appears.
  4. Realtime: a second agent-browser session on a fresh access link sees a change from the first without a reload.
  5. Report the App URLs, the CR link, the flows you ran, and anything you could not verify.

Cost

  • A static App costs nothing.
  • Apps have no monthly budget. Account credits pay for compute; the account billing gate (402, for example app_account_unfunded) is the only gate.
  • An on-demand machine bills only while awake. An always-on machine bills 24/7, with or without traffic.
  • --budget and monthly_budget_usd are retired and ignored.

Tell the user how each App runs (24/7 or on demand) before you hand over. Never quote a price.

Delete

kortix apps delete <slug> --yes                         # the App, its machines, images and the triggers that name it; volumes keep a final snapshot 7 days
kortix apps delete <slug> --deployment <vN> --yes       # one release (not the live one)
kortix apps volumes destroy <slug> <volume> --yes       # admins; a final snapshot is kept 7 days

References

  • references/apps-model.md — releases, machines, volumes, strategies, release_command, checks, scale, services, exec, the env every machine gets.
  • references/web-static.md — static sources, build rules, caching, verify.
  • references/web-server.md — Dockerfile and OCI Apps, process groups, run mode, wake, diagnose.
  • references/convex.md — the Convex template: launch, connect, push, test, dashboard, durability, delete.
  • references/convex-patterns.md — schema, queries, mutations, actions, HTTP actions, crons, files, search.
  • references/sign-in.md — tokens, kortixToken, verifyKortixToken, requireKortixMember, troubleshooting.
  • references/bindings.md — uses links and the /_kortix/apps/<slug> mount.
  • references/connectors.md — calling connectors from an App.
  • kortix-ui skill, references/custom-dashboard.md — a dashboard or App UI on @kortix/sdk + @kortix/ui: workspaces, the session list, the workspace home, the session workspace (thread + side panel), files, a custom tool row, a company theme. references/modules.md: every module entry with its props and an example; references/theming.md: every theme key.