Knowi Apps

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.

Before you begin

  • Confirm that Knowi Apps is enabled and that you have the permissions needed to view, create, edit, or publish Apps.
  • Decide where the source will live. You can use a Knowi-managed repository, your organization's GitHub, or another Git server over SSH.
  • Confirm that App users have access to the intended Knowi assets and rows.

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.

Choose where the source lives

The Repository section offers the source options enabled for your account.

OptionBest forSetup
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.
GitHubOrganizations 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.

Knowi-managed repositories

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.

GitHub

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.

Other Git over SSH

  1. Enter an SSH remote such as git@host:group/repo.git or ssh://git@host/group/repo.git. Leave the branch empty to use the repository's default branch.
  2. Select Generate deploy key, then copy the public key shown.
  3. Add the public key to that repository as a deploy key with write access.
  4. Select Verify. Knowi confirms that it can read and write the repository and shows the pinned host-key fingerprints.

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.

Create and refine an App

  1. Select New App, enter a name and URL slug, choose or create a repository, and select an access mode.
  2. Describe the intended users, Knowi data, pages, filters, actions, branding, and mobile behavior. You may attach PNG, JPEG, or WebP reference images.
  3. Generate the draft. Knowi commits the source and builds that exact commit.
  4. Open the Ready preview. Request another change or publish when the result is approved.

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.

Use the knowi_app MCP tool

An MCP-capable AI client connected to the Knowi MCP Server can use one knowi_app tool:

ActionWhat it does
createCreates an App from an authorized repository.
changeRequests a source change, commits it, and queues a build.
statusReturns 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.

Work with source and build locally

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.

Supported stack

  • Frontend: HTML, CSS, JavaScript, or a frontend framework that builds through the project's npm script.
  • Backend: a Node.js 22 HTTP service. Express, Fastify, Nest, and other pinned npm packages are supported.
  • Storage: optional Managed PostgreSQL for App-owned workflow data.

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.

Repository contract

FilePurpose
app.jsonBuild declaration.
package.jsonBuild script and dependencies.
package-lock.jsonLocked dependencies.
<web source>Your frontend source and assets.
server/app.mjsThe service entry in the generated scaffold.
db.jsonOptional 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.

Build, preview, publish, and roll back

StateMeaning
QueuedThe selected commit is waiting to build.
BuildingKnowi validates and builds the commit, then confirms that the App starts correctly.
ReadyThe version can be previewed or published.
FailedThe candidate did not build or start; the live App is unchanged.
LiveThe 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.

Optional managed App storage

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.

Access and security

Choose an access mode when creating the App or change it later under App settings:

Access modeWho can open the AppKnowi identity boundary
Knowi sign-in requiredEvery viewer signs in to Knowi.Knowi users, groups, roles, SSO, asset permissions, and row-level restrictions apply.
PublicAnyone with the URL can open the App.Identity-required Knowi data and actions remain unavailable.
App manages accessThe 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 and GitHub Enterprise Server

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.

Troubleshooting

ProblemWhat to check
Knowi Apps is unavailableContact your Knowi account representative and ask to have Knowi Apps turned on.
Knowi Apps is enabled but hiddenAsk a Knowi administrator to verify your Knowi Apps permissions.
A source option is missingAsk a Knowi administrator whether that option is enabled for your account.
GitHub repository is missingSelect it in the Knowi GitHub App installation, allow write access, then select Check again.
SSH verification failsConfirm the remote is correct, the deploy key has write access, and the host is reachable over SSH.
AI cannot commitCheck repository write access and branch-protection rules.
Generation setup is incompleteAsk an administrator to configure the App Generation model under AI Settings.
Build failsCheck app.json, the lockfile, build script, dependencies, and service entry. The live App remains unchanged.
A change is not shownRefresh, then select Build to use the latest default-branch commit.
Preview or Publish is unavailableConfirm the version is Ready and that you have the required permission.
AI edit conflictsRefresh and request the change again from the latest version.
The Git host is unavailableThe live App keeps running. Restore the connection before starting another edit or build.
knowi_app is missingVerify Knowi Apps enablement, MCP authorization, and your Knowi Apps permissions.
Cannot create another AppYour 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.