Build, review, and publish applications that turn governed Knowi data into customer-specific workflows and actions. Your App owns its pages, navigation, branding, workflow, and business logic; Knowi manages builds, hosting, governed data access, and releases.
Availability: Knowi Apps is not enabled by default. Contact your Knowi account representative to have it turned on. After enablement, a Knowi administrator assigns the appropriate Knowi Apps permissions.
The flow is Describe → Commit → Build → Preview → Publish.
Source stays in a Git repository. Every App version points to an exact commit, so your team can clone, review, test, and manage it with its normal Git workflow. A Git push does not change the live App; publishing is always an explicit action in Knowi.
A dedicated repository per App is recommended because it keeps permissions, reviews, and releases easy to understand. Knowi sign-in required is the default access mode; a publisher can change it later under App settings.
The Repository section offers the source options enabled for your account.
| Option | Best for | Setup |
|---|---|---|
| Knowi-managed (recommended) | Teams that want to start without setting up their own Git hosting. | Enter a repository name and select Create repository. Knowi creates a private repository and selects it for the App. |
| GitHub | Organizations that keep source in their own GitHub account. | Select Connect GitHub, authorize only the repositories Knowi Apps may use, then select Check again. Writable repositories appear in the list. |
| Other Git (SSH) | GitLab, Bitbucket, Azure DevOps, Beanstalk, or a self-hosted Git server. | Enter the SSH remote and optional branch, generate a deploy key, add it to the repository, and select Verify. |
Options that are not enabled for your account do not appear.
Repository names use 3-60 lowercase letters, numbers, and hyphens. To let a teammate clone, review, or push, open Manage access and add their GitHub username with Read and write or Read only collaborator access. You can remove access from the same list.
A GitHub administrator installs the Knowi GitHub App and chooses which repositories it may use. Knowi sees only the selected repositories. Allow write access if Knowi AI or MCP will commit changes. To change access later, update the selected repositories in GitHub and select Check again in Knowi.
git@host:group/repo.git or ssh://git@host/group/repo.git. Leave the branch empty to use the repository's default branch.A read-only key remains pending until write access is granted. Pending repositories remain listed with Verify and Remove actions. Knowi does not ask for your Git password or personal access key.
Each successful change creates another Git commit and immutable App version. If a person changes the branch at the same time, Knowi rejects the conflicting AI change instead of overwriting the person's work. Refresh and retry from the latest version.
Generation usually takes 5-10 minutes; complex Apps may take up to 15 minutes. Knowi keeps the status updated, so you can leave the page and return later. You can also request cancellation while generation is running.
Before the first generation, a Knowi administrator selects the model for App Generation under AI Settings.
An MCP-capable AI client connected to the Knowi MCP Server can use one knowi_app tool:
| Action | What it does |
|---|---|
create | Creates an App from an authorized repository. |
change | Requests a source change, commits it, and queues a build. |
status | Returns the current status and a short-lived preview when the version is Ready. |
If exactly one writable repository is available, create can select it automatically. Otherwise, use the repository label shown in Knowi Apps. MCP resolves it only against repositories already authorized for the account and requires the appropriate user permissions.
MCP cannot publish, remove an App, change access, select an arbitrary repository, or upload built output. Publish remains an explicit action in the Knowi UI.
The repository is the source of truth. Your team can clone it, create branches, use pull requests, test locally, merge into the configured default branch, and inspect the commit used for each App version. After merging a change, select Build in Knowi.
The backend can define API routes, accept file uploads, call external APIs, send outbound webhooks, and perform request-driven work allowed by your account's App policy. It must listen on process.env.PORT and must not hard-code a deployment port.
| File | Purpose |
|---|---|
app.json | Build declaration. |
package.json | Build script and dependencies. |
package-lock.json | Locked dependencies. |
<web source> | Your frontend source and assets. |
server/app.mjs | The service entry in the generated scaffold. |
db.json | Optional additive managed-database schema. |
app.json identifies the service entry produced by the build and, optionally, the database schema:
{"v":2,"service":"dist/server.mjs","db":"db.json"}
The service value is a relative .js, .mjs, or .cjs path that must exist after the build. The generated scaffold uses server/app.mjs directly.
Build locally with Node 22, npm, the checked-in lockfile, and the declared build script:
npm ci --ignore-scripts --no-audit --no-fund
npm run build
Use the App's governed Knowi API for identity-aware datasets, dashboards, approved HTTP actions, and bounded state. Data writes are accepted only while handling a same-origin mutating request, not from a GET handler. The App may also use its own routes and approved integrations.
Local testing does not deploy an App. Commit the source and select Build in Knowi; prebuilt output cannot be uploaded as a release.
| State | Meaning |
|---|---|
| Queued | The selected commit is waiting to build. |
| Building | Knowi validates and builds the commit, then confirms that the App starts correctly. |
| Ready | The version can be previewed or published. |
| Failed | The candidate did not build or start; the live App is unchanged. |
| Live | The version passed deployment checks and serves the App URL. |
Preview opens only the selected Ready version and never changes the live App. Preview links use a short-lived preview grant and expire; open a new preview from the version list when needed. Depending on configuration, write actions may be disabled or handled safely in preview.
Publish starts and checks the same Ready release before sending live traffic to it. If publishing fails, the previous version stays live. Rollback selects an earlier Ready version without rebuilding the branch. App-owned data persists across releases and rollbacks.
Knowi provisions the App URL, certificate, and routing. Renaming an App changes only its display name; its slug and URL remain stable. Removing an App requires typing its slug and takes it offline. Source history remains in the repository.
A published App does not need the Git host to keep serving. A repository outage or revoked connection prevents new edits and builds, but the live version continues to run.
Enable Managed PostgreSQL when the App needs its own workflow state, such as tasks, approvals, preferences, or action history. Knowi datasets remain the governed source for business data. Provision, test, and revoke storage from the App's Database panel.
An App can use a pinned PostgreSQL client. Its database access is limited to that App. A release may declare an additive schema in db.json; schema changes are applied before the release goes live. A schema failure leaves the current version unchanged. Preview does not use the live managed database, and rollback changes code without rolling data backward.
Choose an access mode when creating the App or change it later under App settings:
| Access mode | Who can open the App | Knowi identity boundary |
|---|---|---|
| Knowi sign-in required | Every viewer signs in to Knowi. | Knowi users, groups, roles, SSO, asset permissions, and row-level restrictions apply. |
| Public | Anyone with the URL can open the App. | Identity-required Knowi data and actions remain unavailable. |
| App manages access | The App handles visitor sign-in and its own sessions. | App identity is not treated as Knowi identity. Identity-required Knowi data and actions remain unavailable. |
Preview access is always protected by its short-lived preview grant. When an App editor with publish permission saves an access change, it applies to live traffic immediately; no rebuild or republish is required.
Selecting App manages access changes the access boundary; it does not create an authentication system. The App source must securely implement and configure its own login and session handling. Use secure, server-managed cookies, rotate the session after login, and do not expose session identifiers to browser JavaScript.
Changing access does not grant new Knowi data permissions. Public and App-managed visitors are anonymous to Knowi. Protected Knowi capabilities remain bound to Knowi identity.
App code does not receive Knowi browser sessions, raw datasource connection details, source-host access, or another App's secrets. Governed Knowi requests are authorized for the current viewer. Never place secrets in Git.
Apps are isolated from other Apps and tenants. Application files are read-only while deployed, resources are bounded, and outbound access follows the account's App policy.
On-premises deployments can use GitHub Enterprise Server when it is enabled by the Knowi administrator. Other Git (SSH) is also available when enabled. Contact your Knowi administrator or account representative before setup.
| Problem | What to check |
|---|---|
| Knowi Apps is unavailable | Contact your Knowi account representative and ask to have Knowi Apps turned on. |
| Knowi Apps is enabled but hidden | Ask a Knowi administrator to verify your Knowi Apps permissions. |
| A source option is missing | Ask a Knowi administrator whether that option is enabled for your account. |
| GitHub repository is missing | Select it in the Knowi GitHub App installation, allow write access, then select Check again. |
| SSH verification fails | Confirm the remote is correct, the deploy key has write access, and the host is reachable over SSH. |
| AI cannot commit | Check repository write access and branch-protection rules. |
| Generation setup is incomplete | Ask an administrator to configure the App Generation model under AI Settings. |
| Build fails | Check app.json, the lockfile, build script, dependencies, and service entry. The live App remains unchanged. |
| A change is not shown | Refresh, then select Build to use the latest default-branch commit. |
| Preview or Publish is unavailable | Confirm the version is Ready and that you have the required permission. |
| AI edit conflicts | Refresh and request the change again from the latest version. |
| The Git host is unavailable | The live App keeps running. Restore the connection before starting another edit or build. |
knowi_app is missing | Verify Knowi Apps enablement, MCP authorization, and your Knowi Apps permissions. |
| Cannot create another App | Your account has reached its Knowi Apps limit. Contact your Knowi account representative. |
For feature enablement, contact your Knowi account representative. For source, build, preview, or deployment problems, contact Knowi Support with the App name, repository name, short commit shown in Knowi, and current build state. Do not include secrets or customer data.