Apps

Deploy static sites, internal tools and backends (data, functions, realtime) from your project to stable URLs, with releases, machines, volumes, access control and Kortix sign-in built in.

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.

Turn Apps on

Apps are off until a platform admin turns them on for a project. A project member cannot turn them on: the write answers 403 feature_operator_only.

• Kortix Cloud: email support@kortix.com with the project id.
• Self-hosted: a platform admin (an email in KORTIX_PLATFORM_ADMIN_EMAILS) who is a project member runs kortix projects features enable apps. For any other project, the admin sends PUT /v1/admin/api/projects/<project_id>/features with {"feature": "apps", "enabled": true} and their sign-in JWT. The instance also needs KORTIX_APPS_BASE_DOMAIN and a wildcard DNS record: see Self-hosting.

While Apps is off:

• Every Apps route answers 403 with code: "feature_disabled", feature: "apps" and the message Apps is not enabled for this project. Contact Kortix to enable it.
• kortix apps <subcommand> exits 1 before it calls the API.
• The project sidebar has no Apps entry. /projects/<id>/apps shows a gate screen.

Check the state with kortix projects features, or in Customize → Settings → Feature flags. Both show apps only while it is on, as a locked row: origin kortix in the CLI, Managed by Kortix in the web app.

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 a v2 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

Rules:

• kortix apps deploy with no arguments deploys every block: each App after the Apps it uses, then by name.
• kortix apps deploy <path> uses the block whose path is that path. --manifest-app <slug> names a block. A flag you pass wins over the block.
• kortix validate applies the same rules as the API. The API refuses a bad config with 400 app_config_invalid and issues: [{ path, message }].
• Any other key is an error. backends is an error: list used Apps in uses. kind is ignored, with a warning.
• A static App ignores the run mode, the machine size, env, secrets and the release config.

Where an App shows

display decides where an App appears in the Apps tab. It never changes how the App runs or who may open it.

An App with preview: none opens on its first tab. Every deploy writes the block’s display; an absent display means the defaults. kortix apps show prints it on the shown row. PATCH /v1/projects/<project_id>/apps/<app_id> with display replaces it whole, and {} restores the defaults. An unknown key, a preview other than live or none, or a malformed parent answers 400.

The full kortix.yaml reference is kortix.yaml reference.

Processes, services and checks

These settings apply to server Apps.

• Process groups. processes maps a group name to a shell command. "" runs the App’s command. A group name is lowercase letters, digits, - or _, and starts with a letter.
• Primary service. http_service answers on the App’s own host. Its fields: internal_port, access, auto_stop_machines (off, stop, suspend; suspend acts like stop), auto_start_machines, min_machines_running (0–100), processes, checks.
• More services. services lists at most 10 more HTTP services, each { name, internal_port, access, processes, checks }. A service answers on <app host>--<name>. http is the primary service’s name and is reserved.
• Workers. A group that no service names is a worker. It runs and never idle-stops.
• Ports. internal_port is 1–65535. Ports 7331 and 8080 belong to the App supervisor and are refused. Two services cannot share a port.
• HTTP only. A service with protocol: tcp is refused. Apps have no TCP services and no private network between Apps.

Service access gates the service’s host:

Checks run inside the machine. A release goes live only when every check of every new machine passes.

Deploy strategy (deploy.strategy):

A release with a mount refuses bluegreen and canary: they would put two machines on one volume. A release that never gets healthy is abandoned, and traffic stays on the previous release.

deploy.release_command (at most 2000 characters) runs once per release, before any machine changes. It runs in a temporary machine with the new image, env and secrets, and no volume. A non-zero exit fails the release with release_command_failed, and nothing changes. Use it for a migration of a database outside the App.

Run mode, machines and scale

A server App runs in one of two modes:

A new App is always on. Change the mode with kortix apps set <app> --always-on or --on-demand, or with always_on in kortix.yaml. The change applies within 5 minutes, without a redeploy. A static App has no runtime and ignores the run mode.

Machine size:

A value out of range answers 400 app_machine_out_of_range. Kortix never clamps it. The App’s size is the default for every process group. On Platinum, a vm entry in the release sizes one group. On Daytona and E2B, every machine uses the App’s size. A size change applies with the next release.

kortix apps machines api                          # id, group, state, release, size, volume
kortix apps machines restart api <machine>        # also start, stop, destroy
kortix apps scale count api 3 --process worker    # 0-20 machines per group
kortix apps scale show api
kortix apps exec api -- node scripts/report.js    # run one command in a machine

• A group runs 1 machine by default. scale count sets 0–20 per group and applies in the background. A new machine of a group with a mount gets its own new, empty volume.
• Destroying a machine keeps its volume. The group runs one machine fewer.
• kortix apps stop suspends a server App now. The next authorized request wakes it. kortix apps start wakes it before traffic arrives. A static App answers 409 static_app_no_runtime to both.
• exec needs project.app.admin and is audited. It takes an argv of 1–256 words, runs in a running machine of the live release (or --machine <id>), and times out after --timeout seconds (1–300, default 60). Each of stdout and stderr returns at most 1 MiB. The CLI exits with the command’s exit code. A stopped machine answers 409 machine_not_running.

Account limits:

A self-hosted instance without billing has none of these limits.

Volumes and snapshots

Volumes need the Platinum sandbox provider. Deploy with --provider platinum when Platinum is not your instance’s default provider. A kortix.yaml block has no provider key. A release with mounts on another provider answers 400 app_volumes_unsupported.

mounts:
  - { source: data, destination: /data, initial_size_gb: 10, snapshot_retention_days: 5 }

• source is the volume name: 1–30 lowercase letters, digits or _.
• destination is an absolute path. It cannot be /, end in /, or sit under /bin, /boot, /dev, /etc, /lib, /lib64, /proc, /root, /run, /sbin, /sys, /usr, /var or /kortix. Use /data.
• Size is 1–100 GB, default 1. A volume grows and never shrinks (400 volume_shrink_refused).
• One machine writes a volume at a time, and a machine mounts at most one volume. Kortix enforces a single-writer lock.
• A volume outlives every release. A rollback changes code and config, never the data.

kortix apps volumes backend                             # name, group, size, attached machine, retention
kortix apps volumes create backend data --size 10 --process app
kortix apps volumes extend backend data --size 20
kortix apps volumes snapshots backend data              # daily, manual and final snapshots
kortix apps volumes snapshot backend data               # a manual snapshot now
kortix apps volumes restore backend data <snapshot>     # project.app.admin
kortix apps volumes fork backend data data_copy         # --snapshot <id> to copy a snapshot
kortix apps volumes destroy backend data --yes          # project.app.admin

Access

An access mode decides who can open one App. It grants no permission that the person’s role denies.

Project managers, account owners and account admins see and open every App of the project, so a private App stays manageable after its creator leaves.

kortix apps deploy dist --app my-site --access project
kortix apps access my-site --mode restricted --members <member_id> --groups <group_id>
kortix apps access my-site --mode password --password '<password>'
kortix apps access-link my-site

• A person who can open the App signs in with their Kortix login. An access link (kortix apps access-link) works for 5 minutes and sets an 8-hour, host-only, secure cookie. Treat the link as a secret.
• A change to the policy revokes every App cookie and every viewer token the App holds. Everyone signs in again.
• Kortix stores only a password hash. The API, the CLI and the SDK never return it: the policy reports password_configured.
• The App list shows only the Apps you may open. An App you may not open answers 404, never 403.
• In the web app, ?open_app=<app_id> on the Apps page opens the App through an access link.

Know who is looking

The gate signs in every visitor before a request reaches your App. Your App reads who they are without a login of its own. The viewer scope decides how much it is told:

kortix apps access my-site --viewer api

A viewer exists when a person opens the App with their Kortix login or an access link. A password App never has a viewer. A public App has one only for a visitor who arrived through an access link.

In the browser. GET /_kortix/viewer on the App’s origin returns the viewer. Call the Kortix API through /_kortix/api/v1/* on the same origin: a direct call to the API from an App origin fails CORS.

import { createKortix, kortixAppViewerToken } from '@kortix/sdk';
import { useKortixAppViewer } from '@kortix/sdk/react';

const kortix = createKortix({ backendUrl: '/_kortix/api/v1', getToken: kortixAppViewerToken() });

function Header() {
  const { status, viewer } = useKortixAppViewer();   // 'loading' | 'anonymous' | 'viewer'
  return <span>{status === 'viewer' ? viewer.email : 'Signed out'}</span>;
}

/_kortix/api/v1/* answers 403 viewer_api_disabled unless the scope is api, 401 no_viewer_identity without a viewer, and 403 cross_site_request for a request from another origin. /v1/oauth/* and MCP paths answer 404.

On the App’s server. Import from @kortix/sdk/server:

import { readAppViewer, createAppViewerKortix } from '@kortix/sdk/server';

const viewer = await readAppViewer(request);
// { userId, email, name, picture, groupIds, groups, role, projectId, accountId, appId, accessMode, token, expiresAt } or null
if (!viewer) return new Response('Not found', { status: 404 });

const kortix = await createAppViewerKortix(request, { backendUrl: 'https://api.kortix.com/v1' });   // scope api only

• readAppViewer verifies the signed header with KORTIX_APP_VIEWER_SECRET, which Kortix injects. A forged header fails.
• createAppViewerKortix builds a client that acts as the viewer, from the token the gate adds to each request. Build one per request. Never store or log the token.
• createKortixAppGuard() returns one resolver for both the gate header and your own Kortix sign-in. requireViewer(request) and requireGroup(request, groupIds) return { viewer } or { response }, never null. A group check keeps working when the App’s access mode changes.
• A viewer with the member role needs an agent grant to start sessions on a project with agent permissions. Without it, the API answers 403 no_agent_access.

An App on its own domain has no gate. Use Sign in with Kortix there.

Apps that use Apps

An App can use other Apps of its project. Then its code gets sign-in tokens for them and reaches them on its own origin.

kortix apps link crm --uses backend  # add; kortix apps unlink removes
kortix apps set crm --uses backend,files # replace; --uses= clears

uses: [backend] in the kortix.yaml block sets the same list on every deploy. An unknown slug, or one you cannot see, answers 400 app_not_found with slugs.

Sign-in tokens. Each project has one token issuer, https://<api host>/v1/projects/<project_id>, with a public /.well-known/openid-configuration and /jwks.json. A token is an ES256 JWT that lives 15 minutes. Its aud is the id of the App it is for. It carries sub, email, name, picture, groups, group_ids, role, account_id and project_id. An agent’s token carries kind: "agent" and no groups or role.

Any other audience answers 403 app_not_linked. A token proves who the person is, not what they may do: check groups or role in every function whose data is not for everyone the App admits. A person you remove loses access within one token lifetime.

Bindings. /_kortix/apps/<slug>/* on an App’s origin forwards HTTP and WebSocket requests to the http service of an App it uses. /_kortix/apps/<slug>--<service>/* reaches another service. Your browser code needs one origin and no CORS. The used App checks the token itself.

import { kortixBinding } from '@kortix/sdk';

const backend = kortixBinding('backend'); // { url: <origin>/_kortix/apps/backend, token: a token fetcher }

Server to server. A machine has no viewer cookie, so it skips the binding. It calls KORTIX_USES_URL_<SLUG> with a token. A link change reaches that variable with the next deploy, because a deploy makes new machines.

Verify a token. verifyKortixToken(bearer) from @kortix/sdk checks the signature, expiry (60 s skew), issuer and audience. In a server App it needs no options: it reads the injected KORTIX_AUTH_* values. Elsewhere, pass the App’s auth.issuer, auth.audience and auth.jwks_uri. To verify offline, for example in a self-hosted Convex deployment, kortix apps auth-env <app> prints KORTIX_AUTH_ISSUER, KORTIX_AUTH_AUDIENCE and KORTIX_AUTH_JWKS (the key set as a data: URL) as dotenv lines. These values are public.

readKortixMember(claims) turns a token’s claims, or a viewer, into one member object, or null. requireKortixMember(claims, { groups, roles }) returns the member or throws KortixMemberError with code unauthenticated or forbidden. Each list means “any one of these”. A group matches by name or id. An empty list admits nobody. Groups need the Enterprise plan; roles work on every plan.

Agents and Apps

An agent session calls an App with its session credential, in Authorization: Bearer or X-Kortix-App-Authorization: Bearer. Use the second header when the App reads Authorization for its own key. Before the gate forwards the request, it removes X-Kortix-App-Authorization, an Authorization header that holds a Kortix credential, and the Kortix cookies. Every other header and cookie reaches the App unchanged. App code never receives a Kortix credential.

The gate judges an agent session as the agent, not as the person who started it:

In a project whose kortix.yaml declares no agents, the gate judges the session as the person who started it. A refused request answers 401 app_auth_required. An agent session opens only Apps of its own project.

agents:
  report-writer:
    kortix_permissions: [project.app.read]
    apps: [reports]    # App slugs, all, or none (the default)

Set the list in kortix.yaml, with kortix agents scope report-writer --apps reports (also all and none; needs a v2 kortix.yaml), or in Customize → Agents → the agent → Apps. The App’s access dialog lists the agents granted to it. From code, call apps.access.agents(appId). See Agents & permissions.

A script, a CI job or a service account calls a non-public App with a personal access key (kortix_pat_) or a service account key (kortix_sa_), in Authorization: Bearer or X-Kortix-App-Authorization: Bearer. The gate applies the same access decision as for a signed-in browser, within the token’s project binding. A password App never accepts a Kortix credential.

An openapi or http connector whose base URL is an App of the same project needs no Kortix credential. The connector gateway adds a signed, 60-second assertion for the calling session. See Connectors.

Environment inside an App

Kortix sets these variables in every machine:

Your own values come from env and secrets in the kortix.yaml block:

• At most 128 env values and 128 secrets mappings. A value is at most 32 KiB.
• A name is uppercase letters, digits and _ (^[A-Z_][A-Z0-9_]*$), at most 128 characters.
• kortix validate and the deploy refuse reserved names: every name that starts with KORTIX_ or OPENCODE_; PORT, PATH, HOME, PWD, USER, LOGNAME, SHELL, HOSTNAME, TERM, TMPDIR, NODE_ENV, NODE_OPTIONS, LD_PRELOAD, LD_LIBRARY_PATH; and SLACK_SIGNING_SECRET, SLACK_BOT_TOKEN.
• A name cannot be in both env and secrets.
• secrets maps a runtime name to a project secret identifier. The secret must have the environment exposure. Kortix resolves it when it creates the machine and never writes it into the image. See Secrets.

URLs and what visitors see

Kortix assigns the hostname when it creates the App and never changes it. On Kortix Cloud it is https://<env>-<slug>-<route-key>.apps.kortix.com, where <route-key> is 16 hex characters. Another service answers on the same label plus --<service>. A service URL is null when the label would pass 63 characters: reach that service through a binding. A self-hosted instance serves Apps on the wildcard domain in KORTIX_APPS_BASE_DOMAIN. See Self-hosting.

A static App serves files at once:

• HTML revalidates on every load (no-cache).
• Hashed build output (_next/static/, and hashed files under assets/ or static/js|css|media/) is cached for a year. Every other file revalidates.
• With SPA fallback on, a page navigation to an unknown path gets index.html. A missing file gets your 404.html with status 404.
• /docs redirects 308 to /docs/ when docs/index.html exists.
• Responses are private to shared caches unless the App is public.

An authorized request to a stopped server App wakes it, waits for readiness and then serves that same request. While the App deploys or wakes, a browser gets a status page with HTTP 202, retry-after: 3 and a 3-second refresh. Other clients get 202 and JSON with a code that names the phase, for example app_deployment_building or app_starting. Retry after 3 seconds.

Account limits answer 402 or 429: see Run mode, machines and scale.

Releases, rollback and deletion

kortix apps releases my-site            # vN, status, strategy; marks the live one
kortix apps show my-site                # capabilities, links, run mode, releases
kortix apps logs my-site [deployment]   # runtime logs; --after N --limit N
kortix apps rollback my-site v3         # a new release from v3; waits unless --no-wait

• A rollback creates a new release from the target’s artifact and config, and rolls it out like a deploy. Volumes keep their data. A target that is not ready answers 409 release_not_ready.
• An App keeps its live release and the 5 newest other ready releases as rollback targets. Kortix retires older ones after each deploy. A self-hosted operator sets the number with KORTIX_APPS_RETAINED_DEPLOYMENTS.
• Runtime log lines carry a source: app (your process), appd (the App supervisor) or caddy (the access log, which never holds request headers).
• In the web app, open the App, then a release, to read its events and build log.

Delete one release, or the whole App:

kortix apps delete my-site --deployment v1 --yes   # one release and its image
kortix apps delete my-site --yes                   # the App, its machines and images

• The live release cannot be deleted (409 deployment_live). Roll back first.
• A release that is still building cannot be deleted (409 deployment_in_progress).
• A build that hits the provider’s image limit fails with app_image_quota_exceeded. Delete releases you do not need.
• Deleting an App needs project.app.write. An App with volumes also needs project.app.admin. Each volume keeps a final snapshot for 7 days, then Kortix purges it. Export data you need first.

Template: Convex backend

The convex template deploys a self-hosted Convex backend with Kortix sign-in: a database, server functions, realtime queries, file storage, schedules and search. It is an ordinary server App with a volume.

kortix apps launch --template convex   # --provider platinum, --no-deploy

Run it in the directory that holds your kortix.yaml. A slug that is already in the file is refused: pick another --name. The backend mounts a volume, so it needs Platinum: pass --provider platinum when Platinum is not your default provider. --no-deploy writes kortix.yaml only.

launch writes two blocks into kortix.yaml and the dashboard’s two files, apps/backend/dashboard/Dockerfile and apps/backend/dashboard/start.js (a file that already exists is kept). It deploys backend, then writes the backend’s admin key to the project secret BACKEND_ADMIN_KEY (the slug in capitals, - becomes _). It reads the key from the machine and never prints it. The key belongs to the backend just launched, so every launch writes it again. Then it deploys backend-dashboard.

There are two Apps because Convex ships the backend and the dashboard as two images, and a Kortix App runs one image. The Apps tab shows them as one: the dashboard is the backend’s Dashboard tab. The backend runs 24/7 with its volume; the dashboard sleeps when idle.

start.js runs Convex’s dashboard on port 6792. On the App’s port 6791 it serves / as a page that frames the dashboard and answers its sign-in request (Convex’s embedding protocol) with the admin key; every other path goes to the dashboard. Only project admins reach the App, so the page may carry the key.

Both backend services are public because Convex checks sign-in in each function. Keep the backend at 1 machine: a second machine gets its own empty volume, which makes a second, separate database.

Connect and push your Convex code, for example from apps/backend/. A session has BACKEND_ADMIN_KEY in its environment:

cd apps/backend
npm install convex@1.46.0 @kortix/sdk
export CONVEX_SELF_HOSTED_URL=<backend App URL> CONVEX_SELF_HOSTED_ADMIN_KEY="$BACKEND_ADMIN_KEY"
kortix apps auth-env backend | while IFS='=' read -r k v; do printf '%s' "$v" | npx convex env set "$k"; done
npx convex deploy

Use Convex CLI 1.46.0: it matches the pinned backend.

Kortix sign-in for the functions:

// convex/auth.config.ts
export default {
  providers: [{
    type: 'customJwt',
    issuer: process.env.KORTIX_AUTH_ISSUER!,
    applicationID: process.env.KORTIX_AUTH_AUDIENCE!,
    jwks: process.env.KORTIX_AUTH_JWKS!,
    algorithm: 'ES256',
  }],
};

// convex/members.ts
import { query } from './_generated/server';
import { readKortixMember, requireKortixMember } from '@kortix/sdk';

export const me = query({
  args: {},
  handler: async (ctx) => readKortixMember(await ctx.auth.getUserIdentity()),   // null when signed out
});

// In every function that touches non-public data:
// const member = requireKortixMember(await ctx.auth.getUserIdentity(), { roles: ['owner', 'admin'] });

In React, read the member with useQuery(api.members.me). Do not call useConvexAuth(): it throws under a plain ConvexProvider.

• Dashboard. Open Apps → backend → Dashboard (project admins). It opens signed in. kortix apps access-link backend-dashboard prints a 5-minute link to the same page.

• A backend launched before the Dashboard tab shows its dashboard as its own card, or asks for the key. Run kortix apps launch --template convex --no-deploy in an empty directory and copy its apps/backend/dashboard/ files and both kortix.yaml blocks into your project. Then write the key and deploy the dashboard:

  kortix apps exec backend -- sh -c "cd /convex && ./generate_admin_key.sh" | tail -n 1 | kortix secrets set BACKEND_ADMIN_KEY=-
  kortix apps deploy --manifest-app backend-dashboard

  Add display: { preview: none } to the backend block; a deploy of backend applies it.

• Before a migration, a bulk import or a backfill, take kortix apps volumes snapshot backend data. Restore with kortix apps volumes restore backend data <snapshot>: the live data returns to the snapshot.

• Keep your own copy with npx convex export --path backup.zip --include-file-storage.

• From outside, kortix apps connect backend prints how to call the backend: its URLs and snippets for a sign-in token, an HTTP call and your own server. It prints no secret.

Build an internal tool

An internal tool 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 calls it.

apps/backend/convex/        Convex functions: schema.ts, auth.config.ts, members.ts, ...
apps/crm/              Vite + React UI: src/convex.ts wires the binding
apps/backend/dashboard/     the dashboard App: Dockerfile + start.js (the template)
kortix.yaml            apps.backend and apps.backend-dashboard (the template), apps.crm

// apps/crm/src/convex.ts
import { ConvexReactClient } from 'convex/react';
import { kortixBinding } from '@kortix/sdk';

const backend = kortixBinding('backend');
export const convex = new ConvexReactClient(backend.url);
convex.setAuth(backend.token);

apps:
  crm:
    path: apps/crm/dist
    type: static
    spa: true
    uses: [backend]

(cd apps/crm && npm run build)
kortix apps deploy apps/crm/dist
kortix apps access crm --mode project

Never use public for internal data. A public App has no signed-in member, so every function that requires one refuses the call.

Build on Apps from TypeScript

kortix.project(projectId).apps in @kortix/sdk exposes every App operation. The CLI uses the same calls.

Branch on an App’s capabilities, never on how the App was made:

A call that needs a capability the App lacks answers 409:

{ "error": "This App does not support exec.", "code": "app_capability_unsupported", "capability": "exec" }

The CLI checks first: it exits 1 with App <slug> does not support <capability>. and sends nothing. The machine and volume routes of an App with no machines answer 409 app_no_machines.

import { createKortix, isFeatureDisabledError } from '@kortix/sdk';

const kortix = createKortix({ backendUrl: 'https://api.kortix.com/v1', getToken: async () => process.env.KORTIX_TOKEN! });
const apps = kortix.project(projectId).apps;

const app = await apps.create({ slug: 'docs', name: 'Docs' });
const artifact = await apps.artifacts.uploadArchive(tarGzBytes);   // register, upload, hash, finalize
const deployment = await apps.deployments.create(app.app_id, {
  artifact_id: artifact.artifact_id,
  source: { kind: 'static', spa: true },
});

for (;;) {
  const { deployment: current } = await apps.deployments.get(app.app_id, deployment.deployment_id);
  if (current.status === 'ready') break;
  if (current.status === 'failed' || current.status === 'cancelled') throw new Error(current.error ?? current.status);
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

isFeatureDisabledError(error) is true for the 403 feature_disabled that a project without Apps answers. React hooks in @kortix/sdk/react: useProjectApps, useAppDeployments, useAppDeployment, useAppAccess, useAppMachines, useAppVolumes and useAppVolumeSnapshots. Signatures and types: SDK reference and React hooks.

Permissions and CLI reference

Every route also needs the project’s Apps switch on. See Accounts & access for roles and custom roles.

<app> is an App id or slug. Every subcommand takes --project <id>, --host <name> and --json.

The whole CLI: CLI. Every route: the REST reference at https://api.kortix.com/v1/docs.