Skip to main content
An App is a data application with a home Room. Database Apps provide standard record views; Custom Apps add their own interface and business logic. An App can expose a typed record contract and documented APIs, so people and agents work on the same data. New structured data is created as an App. There is no separate “table” resource to create first.

​
Database Apps vs Custom Apps

  • Database App — the default. You define the records (entities, fields, relationships); Kylon provisions a database and opens the records in Data Viewer with table, board, and calendar views, saved views, filters, grouping, and record discussion. No source repository or deployment is involved.
  • Custom App — an App with its own source code, for a bespoke interface or App-owned logic: custom pages, dashboards, forms, workflow screens, public sites, or APIs that go beyond record create/read/update/delete. Custom Apps are built and published from drafts, with a preview before release. A database is needed when the App stores records; a static site need not define any.
A Database App can later be upgraded to a Custom App when the standard record experience stops being enough.

​
Find and use an App

Open Apps to find Apps you can access, or open an App from its home Room. Pin an existing App for a personal sidebar shortcut; creating an App and pinning it are separate actions. The template catalog can install a ready-made App into a selected Room; any external connections still need their own authorization. In Data Viewer, people can browse and edit records, change between table, board, and calendar views, and open a record’s discussion. Agents read app docs <app_id> and use the documented app api operations. Saved views, filters, sorting, grouping, and visible fields are shared view configuration managed with app data-view; they do not restrict access to records.

​
Access and sharing

The home Room controls who may build, publish, move, delete, or change the App’s access. The App’s visibility controls who may use it: There is no per-record access control in Data Viewer: everyone admitted to the App can read every record it exposes there. A filtered view is not a privacy boundary. An Agent’s request to widen visibility needs a human’s approval. Use Share for the appropriate link. A private or workspace link requires sign-in; it does not grant access to the Room’s messages or files. An older Custom App may need an update and republish before workspace-wide access is ready.

​
Database App lifecycle

  1. Create the App with app create. It is a Database App unless you pass --runtime-kind custom_app.
  2. Provision its database and define the schema.
  3. Register the entities and fields with app register, so Data Viewer and the App API know the shape of the data.
  4. Operate it: read app docs <app_id> for the generated contract, call it with app api, and adjust shared views with app data-view.
Build a Database App walks through these steps. To react to changes in an App’s records, use an Automation.

​
Custom App drafts and publishing

A Custom App has a published release and working drafts. A draft has its own preview database; edits made in the preview are test data and are not copied into the release. Schema and initial-data changes belong in versioned migrations, which run against the preview before review and against production when published. Review the ready preview before publishing its exact deployment. Publishing changes the deployed code; it does not freeze the App’s live records. You can publish from the draft’s publish control, or ask the Agent to publish the reviewed preview. An eligible human can also grant that Agent standing publish approval for this App, for 24 hours or indefinitely, and revoke it later. Widening access remains a separate human decision. Custom App development workflow covers the source, preview, and release lifecycle.

​
Connected services

New Apps have no external-service grants. An App needs its own explicit connection authorization, even if the building Agent can already use that service. Inspect and manage these with app connections list, grant, and revoke. Keep provider credentials in server-side calls through the App connections proxy.

​
App-managed Automations

An App can declare Automations as part of its registration or source. They appear in the Room’s Automations list as Managed by App. Pause, resume, run once, and credit protection are available there; changing the definition requires updating the App’s declaration. See Automations.

​
Legacy Tables

Before Apps, structured data lived in standalone Tables. Existing Tables remain available until their per-resource cutover, and their table, row, field, and view commands only apply to Tables that have not been upgraded. To move one, run table upgrade-plan <table> and then table upgrade-to-app <table>; after cutover the replacement App is the only copy to use. Do not create new Tables.

​
Reference

The full command surface is in kylon workspace app, the largest workspace subcommand. Prefer the generated reference over memorizing flags.