Skip to main content
Use a Custom App for a bespoke interface, public site, server-side business rules, external integrations, or App-owned APIs. If standard record views and simple record operations meet the need, start with a Database App. This guide covers the Kylon lifecycle: prepare source in a registered draft, review its preview, and publish a release. For application-specific dependencies and implementation, follow the chosen template’s README.

​
Before you begin

Choose the home Room, the App’s users and workflows, and its intended access scope. You need an authorized CLI session and access to manage Apps in that Room. Include --scope-workspace <workspace_id> and --scope-room <room_id> when running as a signed-in person. You can also ask an Agent in that Room to perform these steps.

​
1. Create a draft

Keep the returned App and draft IDs and the local checkout path. For a change to an existing App, list its drafts first and reuse the relevant one:
To start a new draft on an existing App, use app checkout --draft-slug <slug> --draft-title "<change name>". Let Kylon register and materialize the branch; do not create an unrelated Git repository or branch yourself. The product adds the Draft: label, so the title should name the change.

​
2. Build from the appropriate template

In the returned checkout, pull an approved template:
Use data-app for a data application, or data-app --database-app <app_id> when upgrading an existing Database App in place. Preserve that App’s schema and registration unless the requested change calls for a data change. For Apps that store records, provision the database with app db provision <app_id>. Put schema and initial-data changes in numbered files under db/migrations/. Follow the template’s setup and build instructions. For generated-contract templates, edit the App definition, run pnpm generate:contracts, and keep registration and APIs consistent rather than editing generated outputs. External services need explicit grants to the App:
Being available to the builder Agent does not automatically grant a connection to the App. Follow App connections for server-side authentication and access requirements.

​
3. Push and review the preview

Commit your changes and push from the registered draft checkout using Git. The push applies pending migrations to the preview database and builds a preview. Inspect its status and build logs:
Wait for READY, then share the draft link for review. Exercise the intended pages and business operations. Preview record edits stay in the preview database; publishing does not copy test records into production. For API verification, inspect app preview docs <app_id> --draft <draft_id> and use app preview api against that exact draft. app api without preview operates the live App. An App-managed Automation’s Run now also uses live records, even when its declaration belongs to a draft.

​
4. Publish the reviewed deployment

Review the ready preview, then use its publish control to confirm the release and audience. You can also ask the Agent to publish that preview, or publish it directly through an authorized CLI session:
Use the exact reviewed deployment ID. If the preview is stale, update the draft, push, and review the replacement preview first. Publishing applies pending production migrations once and archives that draft. Check the release status and open its published link when ready. private admits home Room members; workspace admits all workspace members; public allows anyone with the published link. Widening access needs a human decision. Standing publish approval, if granted for the Agent and this App, can cover later publishes within its scope; it can be revoked.

​
5. Operate the release

Use the published App link for real work. Read app docs <app_id> before automating record or business operations. A successful write through app api refreshes open views automatically. For a custom hostname, app domain add <app_id> <hostname> returns the required DNS steps, and app domain check <app_id> verifies readiness. Removing a custom domain immediately stops it serving the App; the default address remains. See the full app reference for domain, environment, draft, and release controls.