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.mdpackages/starter/templates/managed/skills/kortix-apps/SKILL.md
GitHubKortix 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
- Run
pwdand inspect the intended source directory before deploying. - Run
kortix workspaces info --json. Readproject_id. - Apps are generally available. Use Apps directly without checking a feature flag or routing to an alternative.
- Do not create an empty App identity first:
kortix apps deployandkortix apps launchcreate it. - Never run
kortix apps deployfrom an uninspected workspace root. It can publish unrelated files as a static App. - New Apps are private. Choose another access mode only when the user asks.
- New Apps have no card on the Apps page: they sit in the Background list
and open to an overview (an external
--urlApp is listed on create; Settings → "Show on Apps page" changes it). Register every App a person opens (a site, a UI, a dashboard) withdisplay: { listed: true }in itskortix.yamlblock, or--listedonkortix 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.
- 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"}'nameis 1–128 letters, digits and. _ : / -, starting with a letter or digit. One event is at most 8 KiB.idmakes a retry fire a trigger once. The answer is202 {accepted, deduped, suppressed, triggers}; a bad token gets401 app_token_invalid, a bad name400. - Declare the trigger (no feature flag;
event: "*"matches every name):
Or:triggers: - slug: handle-reply on: { event: reply.received, app: inbox-poller } run: { prompt: "Answer {{ event.data.subject }}" }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. - 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.
- Prove the wiring with a test event, never with a real check (a real id
fires once):
It takes the real path with an id startingkortix apps events emit inbox-poller reply.received --data '{"subject":"Test"}' --waittest-(the prompt readsevent.testas true) and exits 0 only when a trigger fired. - See what came of every event:
kortix apps events inbox-pollerlists the last 30 days, one row per trigger:firedwith the session,skippedwith the reason,suppressed,failed,pending, orunmatched(no enabled trigger listens; the App's POST answer says so inhint). Read it before you guess why nothing ran. - 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 orkortix.heartbeattoo) for that long tells the trigger's watchers once; the App's next post clears it. - 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
accessoverrides it on that service's host:public(no gate; the service checks sign-in itself, like a backend whose functions callrequireKortixMember),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);apiadds a one-hour token that acts as them (x-kortix-app-viewer-token);offsends 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 callhttps://api.kortix.com/v1from 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
- Model the domain. Tables, fields, relations, and the 5–10 actions
people take. Write it down in
memory/<app>.mdfirst. - Backend App.
kortix apps launch --template convex, then connect, discover and push as references/convex.md shows (launchwrites the admin key to the workspace secretBACKEND_ADMIN_KEYand the dashboard's files toapps/backend/dashboard/; the dashboard is the Dashboard tab ofbackend). - Schema + sign-in.
convex/schema.tswith an index for every filter,convex/auth.config.tsandconvex/lib/auth.tsfrom references/sign-in.md. Storeme.userIdas owner/author ids. Use Kortix roles ({ roles: ["owner", "admin"] }) or groups (Enterprise only; without it thegroupsclaim is empty, so use roles). Do not build a user table. - Functions. Every public query and mutation calls
requireMember(ctx)first. Multi-row changes go in one mutation. Add aninternalseed. - Test the data layer (references/convex.md, step 5): anonymous calls fail; calls with an identity succeed.
- UI. Vite + React + TypeScript,
npm install convex @kortix/sdk. Wiresrc/convex.tsas references/sign-in.md, "The browser", shows. Read the signed-in member with amembers:mequery, neveruseConvexAuth(). 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. - 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 anaria-labelfor every icon button; every drag-and-drop action also has a click path; responsive at 1280 px. - Build, deploy and link the UI.
Never(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 backendpublicfor internal data: a public App has no signed-in member. - Integrations only through Kortix connectors (references/connectors.md).
- 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.
- Every App:
kortix apps show <slug> --json; fetchapp.url(references/web-static.md, Verify). A server App also runs references/web-server.md, Verify:kortix apps machines <slug>shows every machinestarted. - A backend App: an anonymous call fails; the same call with an identity
succeeds; a call with
kortix apps tokenanswers"status":"success"(references/convex.md, step 5). - The deployed UI as a member:
kortix apps access-link <app> --json→ openaccess_session.urlwithagent-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. - Realtime: a second
agent-browsersession on a fresh access link sees a change from the first without a reload. - 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 exampleapp_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.
--budgetandmonthly_budget_usdare 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 —
useslinks 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.