Documentation

How Core works

Your people are already building their own software; Core gives them somewhere it's safe. It is one database for the whole team, a complete set of apps on top that is good to work in from day one and that anyone can make their own by asking, and an agent that is the main way in. The apps can't store or send data, so there is one copy of it. This page covers all of it, from the kernel's rules to the API.

01Concepts

Core has three layers, and the colours in the product always mean the same thing:

Words you'll see

• The kernel: the database layer, and the Kernel view in the app where admins manage types and who may see and change them, and everyone can read the log.
• Built-in: the version of an app that ships with Core.
• Your version: your own copy of an app, changed by you or by the agent for you. Only you run it.
• Team version: a version an admin published; everyone without their own version runs it.
• Component: a piece of an app (a list, a card, a metric) that can be mounted on its own: as a Home widget, or inline in the chat.
• Via: where a write came from. Every log entry carries one.

02Run it locally

Core is a TypeScript monorepo (npm workspaces, ESM). One Node process serves the API and the web.

git clone <your fork> core && cd core
npm ci
npm run dev       # API on :3030 (tsx watch) + vite on :5180, proxied

Open http://localhost:5180/app and sign in as any of the six people in the demo workspace with the passcode (core unless you set CORE_PASSCODE). The database is created and seeded on first boot; delete the file to start over. The demo is Halden Studio, a six-person design studio in Amsterdam, with dates relative to the day it was seeded.

npm run build     # server tsc + web vite → packages/server/public
npm run start     # the built server (seeds data/core.db on first boot)
npm run verify    # end-to-end checks on a scratch database

03Types & fields

The kernel holds records of types. A type (its schema) has a key, a label and plural, a title field, an icon, the roles that may read it and write it, and its fields. The demo workspace ships ten: company, contact, deal, project, task, invoice, doc, message, event and file.

// Schema
{ type: "task", label: "Task", plural: "Tasks", titleField: "title", icon: "✓",
  read:  null,                 // or ["finance"]: who may read besides admins
  write: null,                 // or ["finance"]: who may write besides admins
  fields: [{ key, label, type, required?, options?, ref?, help? }], sort }

Every write is validated and coerced against the fields. There are eleven field types:

Empty values ("", [], null) are stored as null. Required fields must be set on create, and a patch can't clear them. A field that isn't in the schema is refused, never added:

400 “estimate” is not a field of Task. Apps can't add fields; an admin adds them in the kernel.

Error messages are sentences meant for people: show them next to the control that caused them.

04Records

Apps, the API and the agent all see the same shape: fields flat, metadata under _.

{ id: "task_juzxwj",
  title: "Design the vehicle add-on step", status: "doing", assignee: "lotte",
  project: "project_asa3fq", due: "2026-10-28", …every field, null when empty
  _type: "task", _title: "Design the vehicle add-on step",
  _labels: { assignee: "Lotte Bakker", project: "Waddenveer booking app" },
  _createdAt, _createdBy, _updatedAt, _updatedBy }

• Ids are short, URL-safe and prefixed by type: task_8f2k1q.
• _labels has display strings for ref, account and accounts fields, so you rarely need a second lookup. A ref to a record you can't read is labelled "Restricted", never with its title.
• _title is the title field's value, or “Untitled task”.
• Keys starting with _ and id are ignored on write, so you can pass a whole record back as a patch.
• Deleting a record that other records point to is refused (409), naming up to three of them.
• Invoice numbers are unique: a create or update that reuses one is refused (409).
• A patch that changes nothing writes nothing and logs nothing.

05Permissions

There are four roles: admin, finance, sales and member. Access is set per type and per role: each type says who may read it and who may write it.

• An admin may read and write every type.
• If a type's read is null or empty, everyone may read it; otherwise only the listed roles (and admins).
• The same for write, with one more rule: writing needs reading. A role that can't read a type can't write it either.

So Maya (admin) and Sam (finance) see and change invoices; Maya and Priya (sales) change deals and Sam sees them; Lotte, Daan and Ruben (members) see neither.

The kernel checks this on every read and every write, whichever app, version or agent makes the call, and on every path a record could leak through: the live copy apps read from, the stream, search, aggregates, backlinks, ref labels and the log. Rules for single records or single fields aren't built yet, and the four roles are fixed.

What a restricted read looks like

The schemas themselves stay visible to everyone, with their read and write, so an app can say who may see a type instead of showing an empty list as if there were nothing. Check with kernel.can(type) (read) or kernel.can(type, "write"):

if (!kernel.can("invoice")) {
  el.innerHTML = `<p class="empty">Invoices are visible to finance and admins.</p>`;
}

Apps should disable what the person can't change, but they don't have to: the kernel says no either way.

403 Only sales and admins can change deals. You're signed in as Sam Okafor (finance).

Who decides

Admins do, in the Kernel view, through the API (PATCH /api/schemas/:type/access) or by asking the agent. A change takes effect everywhere at once: every open shell refetches its live copy, so apps gain or lose records on screen without a reload. It's logged as a kernel change by that admin (“Maya let finance read Invoices”) and can be undone from the log. Anyone else gets a sentence naming the admins.

Changing types and fields, publishing team versions and undoing someone else's change are admin-only too.

06Query, search, aggregate

The same query semantics run on the server, in every app's sandbox and for the agent, so a watch and a REST call always agree.

Query

{ where:  { status: "todo", due: { lt: "2026-10-26" }, assignee: { in: ["daan", "lotte"] } },
  sort:   "-priority,due",   // "-" = descending; comma for ties
  limit:  20, offset: 0 }

Several conditions are ANDed. Sort also takes _title (the default), _createdAt and _updatedAt; empty values sort last either way. A where or sort on a field that doesn't exist is an error that lists the type's fields.

Search

Case-insensitive substring over every text and longtext field of every type. Title hits rank first (exact, then prefix, then anywhere), then the most recently updated. A record also matches when every word of the query appears in its text, the names of the records and people it links to, or its type name (“Kunsthal invoice” finds the Kunsthal invoice); those rank after direct text hits, records of the named type first. 20 results by default, at most 100.

Aggregate

{ type: "invoice", metric: "sum", field: "amount",
  groupBy: "issued:month", where: { status: "paid" } }
→ { metric, field, groupBy, value, count, groups: [{ key, label, value, count }] }

• metric: count (default), sum, avg, min, max. All but count need a number or money field; sum and avg round to cents.
• groupBy: any field. Date and datetime fields (and _createdAt/_updatedAt) bucket with :day, :week (the Monday it starts on), :month or :year. An accounts field counts a record once per person. Empty values group as “None”.
• Groups are sorted by value, largest first; time buckets chronologically.

07The log

Every write is logged with the full record before and after, a title, who made it and via what:

{ id: "log_…", at, accountId: "sam", op: "update", type: "task", recordId: "task_…",
  title: "Send the milestone 2 invoice to Waddenveer",
  before: { …full data }, after: { …full data },
  via: { kind: "agent", threadId: "thread_…" },
  revertedBy: null, reverts: null }

App code never sets via. The shell knows which sandbox made a call and attaches it; the server then trusts only the appId and versionId, checks that the version is the person's own or the team's, and fills in the name and provenance itself. A draft is an agent-made view in the chat: it has no saved version and may name the chat thread it came from.

Ops are create, update, delete, revert, schema (types, fields and who may read and write a type) and app (versions saved, published, switched).

An access change is a schema entry with type set and the full schema before and after; its title reads as a sentence after the admin's name:

{ op: "schema", accountId: "maya", type: "invoice", recordId: null,
  title: "Let finance read Invoices",  // shown as “Maya let finance read Invoices”
  before: { …schema, read: ["finance", "member"] },
  after:  { …schema, read: ["finance"] },
  via: { kind: "kernel" } }

You only see entries you're allowed to: entries about records of a type you can't read are left out, from /api/log, kernel.log and the stream alike. Schema and app entries are visible to everyone.

08Undo

Any record write can be undone from the log, by the person who made it or by an admin (who must also be allowed to write the type):

• create → the record is deleted, if it hasn't changed since and nothing points to it.
• update → the changed fields get their old values back, if none of those fields changed again since. Other fields are left alone.
• delete → the record comes back with the same id.

Restored values must still pass today's schema (an option that was removed, a ref that was deleted); otherwise the undo is refused with the reason. An undo is itself logged with op: "revert" and reverts pointing at the original, which gets revertedBy. An undo can't be undone; make the change again instead. App versions are restored from the app's Versions menu, not the log.

An access change can be undone too, by an admin: who may read and write the type goes back to what it was, logged as a revert with recordId: null. It's refused (409) if access to that type changed again since; undo the later change first. Undoing an entry about a record you can't read is a 404.

09Changing the schema

Admins own the schema: they add types, add fields, edit a select field's options and decide who may read and write each type, in the Kernel view or through the API. Each change is logged with op: "schema" and pushed live to every open app, so a new field shows up without a reload.

• Field keys are derived from the label in camelCase (“Close date” → closeDate) unless you give one: a lowercase letter, then letters and digits.
• A select needs options; a ref names an existing type.
• Fields are never removed or renamed. Options can be removed only when no record uses them.
• A new type with no fields gets a required name text field as its title.

10Anatomy of an app

An app is one HTML fragment: a manifest, markup, a <style> and one or more <script>s. Core places it in the <body> of a sandboxed iframe, after base.css and the runtime that defines the global kernel. Built-ins live at packages/apps/<id>/app.html; tasks is the reference to copy.

<!-- manifest first -->
<script type="application/json" id="core-manifest">
{ "name": "Follow-ups", "glyph": "↻", "description": "Tasks that came out of client mail.",
  "reads": ["task", "company"], "opens": [],
  "components": {
    "due": { "title": "Follow-ups due", "description": "Open follow-ups, soonest first.",
             "props": { "company": "company id, optional" }, "home": true } } }
</script>

<div class="toolbar"><h1>Follow-ups</h1><span class="spacer"></span></div>
<div id="rows"><div class="skeleton"></div></div>

<script>
  const { esc } = kernel.ui;
  function draw(el, tasks) {
    el.innerHTML = tasks.length
      ? `<ul class="list">${tasks.map((t) => `<li>${esc(t.title)} <span class="pill">${kernel.fmt.relday(t.due)}</span></li>`).join("")}</ul>`
      : `<div class="empty"><strong>Nothing to follow up</strong></div>`;
  }
  const open = (company) => ({ where: { status: { ne: "done" }, ...(company && { company }) }, sort: "due" });

  // components register at the top level, synchronously
  kernel.component("due", (el, props) => kernel.watch("task", (rows) => draw(el, rows), open(props.company)));

  // full-screen init only in app mode
  if (kernel.mode === "app") kernel.watch("task", (rows) => draw(document.getElementById("rows"), rows), open());
</script>

11The manifest

A <script type="application/json" id="core-manifest"> at the top. Saving an app checks that it parses, has a name, and that the source has at least one real script; sources are capped at 512 KB.

12Runtime API

The runtime defines a global kernel before your scripts run. Reads are answered from the shell's live copy of the kernel, so they're instant; writes go to the server with your app's provenance attached. Calls return promises that reject with an Error whose message is a sentence for people.

Data

Who, where, when

Shell & helpers

Uncaught errors (and errors from a watch with a bad query) show in the shell's error band with “Ask Core to fix”. The runtime also keeps the theme in sync and passes ⌘K / Ctrl-K through to the shell.

13Components & inline mode

Components are how a piece of one app shows up somewhere else: on Home, or in the chat when the agent brings it up. Register them at the top level of your script, synchronously (never after an await):

kernel.component("task", (el, props) => {
  return kernel.watch("task", ([t]) => {
    el.innerHTML = t ? `<div class="card">${kernel.ui.esc(t.title)}</div>` : `<div class="empty">This task was deleted.</div>`;
  }, { where: { id: props.id } });   // return the cleanup: the unwatch
});

In inline mode the runtime hides the app's own markup, creates #core-inline and calls render(el, props) once your scripts have run. New props call your cleanup and render again. Guard full-screen init with if (kernel.mode === "app") so it doesn't run inline.

• Compact, live (use watch) and interactive: writes are allowed.
• Good from 320 to 720 px wide. The shell sizes the frame to your content, up to about 560 px tall; don't use vh.
• Built-in apps ship at least three: a list or board, a single-record card ({id}), and a summary or metric.

14Talking to the agent

The chat knows which app you have open, its version and its props. Tell it what the person is looking at, so “change this task” just works:

kernel.setContext({ selected: "task_8f2k1q", filter: "mine" });   // app mode, ≤ 2 KB, replaces; null clears

kernel.ask(text) hands text to the agent, as the app (the chat labels it with your app's name). It sends by itself from a full-screen app or within a few seconds of a click; otherwise it fills the composer for the person to send. At most once every 5 seconds per app; call it from a click.

15The sandbox

Every app runs in:

<iframe sandbox="allow-scripts allow-forms" srcdoc="…">
<meta http-equiv="Content-Security-Policy" content="
  default-src 'none'; script-src 'unsafe-inline';
  style-src 'unsafe-inline' <origin>; font-src <origin>;
  img-src data: blob:; connect-src 'none'; form-action 'none'">

No network (no fetch, no WebSocket, no external images), no storage (an opaque origin has no localStorage, IndexedDB or cookies), no popups or new tabs, no alert/confirm/prompt. Core's fonts (Atkinson Hyperlegible Next and Mono, and Anybody for display) are loaded for you. This is what makes “apps never store data” true rather than a guideline: an app physically can't keep its own copy.

The way out is a MessagePort. The document says hello once with a single-use nonce the shell baked into it and gets a port back; everything travels on that port. A frame that navigates away leaves its port behind and is cut off with an error, so never navigate the frame yourself (location.href, reload, links with href): use kernel.open and kernel.link.

16base.css

Loaded into every sandbox so apps look native with little CSS of their own. Light and dark come from prefers-color-scheme and the shell's data-theme; use tokens, never raw colours.

Tokens

Primitives

The iframe's width is your app's width: use @media for narrow layouts (phones, or desktop with the chat dock open).

A personal look

Each person can have their own look: their own values for these tokens, in light and dark, set by asking Core ("I love orange, make it rounder") or with PUT /api/me/look. Core adds it after base.css in their shell and in every app, component and view they run, live, and on nobody else's screen. A look may set the surfaces, text, lines, --kernel/--accent and --yours families, states, radius, fonts, shadows and --lip-color; never the agent's sulphur or people's --p-* colours. So: use tokens, and never redefine them in your app (:root { --kernel: … }) unless the app is meant to have colours of its own.

17Versions

Anyone can save their own version of any app: by hand in the Source drawer, or by asking the agent. Each save is a numbered version with a summary and an author (human or agent), and becomes what you run. What someone runs resolves yours → team → built-in.

• Versions menu: your history; restore any of your versions, or go back to the team or built-in version (your history is kept).
• Publish to team (admin): your version becomes the team version; you then run the team version too.
• New app: a custom app is yours alone until an admin publishes it.

18Checklist for a good app

• Everything on screen comes from kernel.watch; every change goes through create / update / remove.
• Catch write errors and show e.message next to the control.
• Escape every record value with kernel.ui.esc before it goes into innerHTML.
• Loading (skeletons until the first watch fires), empty and error states. Keyboard reachable.
• Disable what the person's role can't do (kernel.can(type, "write")). When kernel.can(type) is false, say who can see the type rather than “nothing yet”.
• Dates: compare with kernel.today(); show with kernel.fmt.
• kernel.setContext when the selection changes; handle deep links with kernel.onprops.
• At least three components; one marked "home": true. Check light, dark and 390 px.

19The agent

Chat is the primary interface. On Home it's the big composer (“Ask anything, or describe a change”) with your threads; with an app open it sits in a dock on the right (⌘K / Ctrl-K focuses it; a full-screen sheet on phones). The open app, its version, its props and its setContext state go with every message.

It runs on the server as the signed-in person, with their permissions: it can't read a type they can't, and nothing from one goes into its context. It can:

• Answer from the kernel: query, search, aggregate and read the log, live.
• Write records: logged via: {kind: "agent", threadId} and undoable from a card in the chat, from the log, or by asking it to undo.
• Change any app for you: it rewrites the current source as a new version of yours (author_kind: "agent") and shows an app-change card with Open, Undo and a summary of the change.
• Build new apps from a description.
• Bring up any component of any app live in the conversation, or write a one-off view (a small chart or table in the same sandbox and runtime).
• Navigate: open an app or a record for you.
• Add fields and change who may see and change a type, if you're an admin, logged the same way as from the Kernel view. Anyone else is told who can.

When it rewrites an app it follows the same rules as everyone: the kernel is the only source of truth, prefs hold UI settings only, it can't add fields (it names the missing field instead), it keeps existing components and a valid manifest, and it writes code a person could read and edit.

20Tools

Every tool runs as the person, through the same kernel functions as the REST API. Tool errors go back to the model as sentences, so it can correct itself.

21Chat API & stream

context is where the person is: {view: "home" | "app" | "kernel", app?: {id, name, versionId, n, prov, props, state}}. from marks text an app handed over with kernel.ask. Messages are saved as blocks (text, tool summaries, embeds, errors), so a reloaded thread re-renders its embeds live.

22REST API

JSON over HTTP under /api. The shell, the agent and your scripts all use the same kernel functions, with the same validation, permissions and log.

Auth

Everything else needs the session cookie and answers 401 {"error": "Sign in first."} without one.

Errors

{"error": "A sentence."} with a 4xx status: 400 invalid, 401 signed out, 403 not allowed, 404 not found, 409 conflict (references, a duplicate invoice number, undo), 413 too big, 429 rate limited.

Where writes come from

Writes take an optional via: {kind: "kernel"} (the default) or {kind: "app", appId, versionId, prov}, where versionId must be your own or the team's version of that app (null for the built-in). Agent and seed writes never come through REST.

Bootstrap

Records

curl -s -b cookies.txt 'localhost:3030/api/records?type=invoice&where={"status":"sent"}&sort=due'
curl -s -b cookies.txt -X PATCH localhost:3030/api/records/task_juzxwj \
  -H 'content-type: application/json' -d '{"patch": {"status": "done"}}'

Log

Schemas

Apps & versions

Prefs

Your look

Live stream

GET /api/stream is a server-sent event stream; the shell keeps one open and pushes changes into every sandbox's watches, which is how a write by the agent shows up in an open app the moment it happens. A comment heartbeat goes out every 25 seconds. Each event is built for whoever the session is signed in as when it's sent: record and log events about a type you can't read are dropped, and ref labels are redacted. Switching person or signing out ends the session's streams; the shell reconnects and refetches the bootstrap.

23Self-hosting

Core is one Node process and one SQLite file (WAL mode). Built, it serves the landing page at /, these docs at /docs, the app at /app and the API at /api.

npm ci && npm run build
PORT=3030 DB_PATH=/var/lib/core/core.db CORE_PASSCODE='…' ANTHROPIC_API_KEY='…' \
  NODE_ENV=production node packages/server/dist/index.js

Configuration

Set in the environment or a .env file in the working directory (the environment wins).

Production

• Run one instance (SQLite has one writer); the repo has a pm2 config (ecosystem.config.cjs).
• Put nginx in front and don't buffer /api/stream or /api/chat: both are event streams. The server also sends X-Accel-Buffering: no.
• Back up the database file; it's the only state there is. That's the point.
• Schema changes in later versions are additive and run on boot.

Open the demo workspace →