An App is the thing you name, keep, and re-run. You describe what you want in one sentence; the runtime writes a small set of files for it, saves them, and runs them on demand. You do not have to write code to get through this page.

By the end you will have an app called Release Notes Writer sitting in your catalog, five files you can read and edit, and a run you can repeat.

What you need

Linux (x86_64 or aarch64) or an Apple Silicon Mac — the installer has no prebuilt binary for an Intel Mac or for Windows yet, and says so rather than installing the wrong thing. You also need a model the runtime serves locally. The agent that writes your app's files is a model; with none served, the scaffold step cannot run. See Local inference for how to get one running.

The short version

Kortecx runs as a managed service — there is nothing to install.

Talk to us. Everything on this page works from there; the runtime is the same one these docs describe.

Local install is not publicly available right now

A public runtime release is planned under a separate repository. Until then the console is the way in.

Start the runtime

The runtime is the program that actually runs your app and records what it did. Start it and leave it running in this terminal.

kx serve --dev-allow-local

--dev-allow-local is the auth posture: accept callers on this machine only. It is not optional — a bare kx serve exits with a usage error rather than opening an unauthenticated server. The alternative is --auth-token <token>=<party>.

Startup lines print to the terminal as the runtime comes up. One of them reads web console ready with the console URL. The defaults are:

web console — http://127.0.0.1:8888/
gRPC — 127.0.0.1:50151
the live-event WebSocket — 127.0.0.1:50152

Your data (the journal, the content store, the catalog) resolves under ~/.kortecx and survives restarts. You never pass a path.

Check a model is served

In a second terminal:

kx models list

Each row is a model the runtime knows about; the one currently loaded is marked (serving). If nothing is listed, or nothing is marked (serving), stop here and set up Local inference first. The next step needs a model to write with.

Open the web console

Open http://127.0.0.1:8888 in a browser. The gateway address is pre-filled (http://127.0.0.1:50151); press connect.

The console is served by kx itself. There is nothing else to install, and it only listens on this machine — a non-loopback console address is refused.

Describe your app in one sentence

Click Apps in the sidebar, then New App. (The same button reads Close while the panel is open.)

Leave the kind toggle on Scheduled — that is the automation lane, the one this page is about. (Hosted is a different lane: a small web project served on a local port. See Hosted apps.)

Fill in two fields:

App name — Release Notes Writer
Goal — Summarize a changelog into release notes

Everything else is optional. The Prompt box (the instruction the model runs each time) defaults to your goal. The model selector defaults to Served default. Skip both for now.

Press Create and scaffold.

Two optional fields, explained

Ground on dataset (RAG) attaches a corpus the agent can search while it runs. The chips only appear once you have ingested a dataset, and dataset search requires a build with the hnsw feature — see Datasets. Guidance rule is one line the agent must always follow, for example Always cite sources.

Watch it write the files

The form turns into a live view: a file tree on the left, the file currently being written on the right, streaming in as the model produces it. Finished files get a ✓, the one in flight gets a ◐, the rest are still pending.

This progress is read from the runtime's real state — which files have committed to the app's branch, and which phase the scaffold reports (planning → writing → done). It is not a timer.

The scheduled lane writes a fixed skeleton of five files. The structure is fixed and pinned by a test; the model writes the contents of each one, in this order:

README.md

app.json

system.md

guardrails.md

main.md

File	What the model is asked to write
`README.md`	what the app does, how to run it, its inputs and outputs
`app.json`	a plain JSON object: name, one-line description, model route intent, high-level steps
`prompts/system.md`	the system prompt that steers the agent's behaviour
`rules/guardrails.md`	the rules the agent must always follow — safety, scope, refusals
`skills/main.md`	the primary skill: a focused instruction plus the tools it may use

Earlier files become context for later ones, so the guardrails and the skill are written knowing what the README and app.json already said.

The files live in the app's own content-addressed branch inside the runtime. Your filesystem is never written. If the scaffold is interrupted, running it again writes only the files still missing.

When the phase reaches done, an Open button appears.

Read it, then run it

Open puts you in the app's editor. The tabs are Files (the file tree with an editor over it), Lineage (a read-only diagram of the app's steps), Skills, MCP Tools and Integrations. Read prompts/system.md first — that is the app's behaviour in plain English. You can edit it in the Files tab and save, or use Modify in the header to ask the agent for a change and approve the diff before it lands.

To run: press the play control on the app's card in Apps, or Run in the editor header. A drawer collects the app's inputs (an app with no input fields runs straight away), then routes you to the live run view, which updates as each step commits. Every step is recorded, so you can go back through it afterwards.

The same thing from the command line

The console does four things in order: save an app, scaffold it, list its files, run it. Each has a command.

An app wraps a small workflow, so the command-line path starts by writing that workflow to a file. This one is a single step: give the model an instruction. It runs offline, no gateway needed.

kx chain run "write" \
  --task write='{"kind":"model","prompt":"Summarize the changelog I am given into release notes."}' \
  --dry-run --emit-blueprint release-notes.dag.json

Wrap it as an app and save it to your catalog:

kx app new "Release Notes Writer" --from-blueprint release-notes.dag.json --output release-notes.app.json
kx app save release-notes.app.json

The handle is derived from the name: apps/local/release-notes-writer.

Now the step the console's Create and scaffold button performs — the agent writes the five files:

kx app scaffold apps/local/release-notes-writer --goal "Summarize a changelog into release notes" --wait

--wait polls the scaffold status and prints it, stopping when the scaffold reports done or failed — or when --timeout-secs (default 120) runs out, whichever comes first. Writing five files with a local model often takes longer than that, so the command may well return while files are still pending. Run the same command again: it resumes and writes only the files still missing.

Read what it wrote:

kx app files apps/local/release-notes-writer
kx app cat apps/local/release-notes-writer prompts/system.md

Run it:

kx app run apps/local/release-notes-writer --wait

And to see everything in your catalog:

kx app list

Both surfaces, one runtime

The console, the command line, and the SDKs are all clients of the same runtime over the same wire. An app created in one shows up in the others. Nothing on this page is a console-only feature.

Two things worth knowing early

Your app can pause for your approval. Add --require-approval to a run and any irreversible, world-mutating tool call stops and waits for you to allow it, rather than firing. Pending requests appear in the console's approvals inbox and under kx approvals list, where you grant or deny them by request id. The app you just built has no tool steps, so nothing will pause yet — the flag matters as soon as an app can touch the outside world.

kx app run apps/local/release-notes-writer --require-approval --wait

One app is one run. An app does not call another app — there is no mechanism for that at any layer. When you need several agents on one job, they chain inside one app: the app's blueprint is a graph of steps, and multi-agent patterns are authored with kx swarm --pattern supervisor (or swarm / consensus). See Workflows.

Your First App

The short version

Start the runtime

Check a model is served

Open the web console

Describe your app in one sentence

Watch it write the files

Read it, then run it

The same thing from the command line

Two things worth knowing early

Where to go next

Scheduled apps

Approvals

On this page