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. It requires AI Agents access on the account and the Knowi Apps feature itself; contact your Knowi account representative to have both 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.
  • For a Knowi sign-in App, confirm that its viewers have access to the intended Knowi assets and rows. For a Public or App-managed App, review any selected dataset carefully because its results can be exposed without a Knowi viewer identity.

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.

Knowi Apps uses its own permissions, assigned by a Knowi administrator:

PermissionAllows
apps:editSee Knowi Apps, create, describe changes, generate, build, and manage App settings.
apps:publishPublish a Ready version, roll back, and apply a live access or custom-domain change.
apps:deleteRemove an App.
apps:shareShare an App with other Knowi users and groups.

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. Select the governed datasets or dashboards the App should use, then describe the intended users, pages, filters, actions, branding, and mobile behavior. You can also attach design references and brand assets.
  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.

If the only thing you changed is configuration - the access mode, the attached Knowi assets, the database setting, or the attached images - select Generate Draft with an empty prompt and Knowi writes the change description for you. A name change on its own still needs a prompt.

App Generation requires a frontier model. If you do not select one, Knowi chooses an appropriate model from an external provider, such as Anthropic Claude, OpenAI, or Google Gemini. Unlike the Knowi model used for Agentic BI features, App Generation models are not hosted entirely in-house. A Knowi administrator can optionally select a customer-provided model under AI Settings; that override requires the provider's API key.

Attach design references and brand assets

Two buttons sit under the prompt box. You can also drag images onto the composer.

ButtonWhat it isAcceptedWhat happens to it
Add design referenceA mock, screenshot, or style sample showing the look you want.PNG, JPEG, or WebP up to 4 MBShown to the model while it writes this draft, then discarded. It never enters the repository.
Add brand assetA logo or image the App itself should display.PNG, JPEG, WebP, or SVG up to 1 MBCommitted into the repository at web/assets/<name> and served by the App at /assets/<name>.

One generation can carry up to four design references and four brand assets, totaling 8 MB across both. An App can hold up to 12 uploaded images, totaling 24 MB, that no generation has used yet. Remove one before adding another if you reach that.

Knowi reads each image's real type from its bytes and rejects a file whose extension does not match. PNG files must be no more than 4,096 pixels on a side and 12 megapixels. SVG is stored and served exactly as uploaded, so it is accepted only when it carries no active content: no <script>, no on... event attributes, no javascript: URL, no <foreignObject>, and href values limited to #fragment or data:image/.

Knowi derives a brand asset's committed file name from the file you upload: lowercased, unsupported characters folded to hyphens, the extension set from the detected image type, and the base trimmed to 48 characters. When the App already has that name, a -2, -3 suffix is added. The list shows the final /assets/<name> path once the upload finishes; use that exact path in later prompts and in App code.

Both kinds are consumed by the generation that uses them. After the version is created, Knowi discards the stored image bytes: a design reference leaves nothing behind, and a brand asset lives on in Git, so every later version keeps serving it without another upload. Upload a brand asset again only to add or replace one.

Remove an image from the list before generating if you change your mind. An image a generated version already used cannot be removed, and a used brand asset keeps its name reserved so a later upload does not collide with it.

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, optionally supplies the complete dataset/dashboard selection, 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.

Just say what data you want when you describe the app, such as "show my sales orders". Knowi finds it among the dashboards and datasets you are allowed to see and saves that choice with the app. Your access is checked again every time the app is previewed or published.

OAuth and manually generated MCP tokens use the same Knowi role and App permissions. There is no separate Apps token or knowi.apps scope.

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, the optional database schema, and the exact governed capabilities used by that source version:

{
  "v": 2,
  "service": "dist/server.mjs",
  "db": "db.json",
  "bindings": [
    {"key": "sales-orders", "type": "data", "id": 1234},
    {"key": "sales-overview", "type": "dashboard", "id": 5678},
    {"key": "crm", "type": "http", "connection": "crm-production"}
  ],
  "branding": {
    "name": "Oakland Case Work",
    "logo": "web/assets/logo.svg",
    "colors": {"background": "#0b1b2b", "button": "#2f6df6", "buttonText": "#ffffff"}
  }
}

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. bindings is required; use [] when the App needs no governed capabilities.

Each binding has a stable key that App code uses, such as data.query({binding: "sales-orders"}). The key is only a source-level name - it is not an API key or secret. data and dashboard bindings identify an exact Knowi asset. http and workspace bindings refer to an existing App connection, keeping destinations, policy, and encrypted credentials outside Git. An App may declare up to 64 bindings; keys and connection names are 1-64 letters, digits, ., _, or - and must start with a letter or digit.

branding is optional and applies only to a Knowi sign-in App; see Sign-in branding.

The manifest is versioned with the source, so restore, rollback, Git review, and AI regeneration all use the same declarations. Knowi validates them during build, rechecks the editor's access for preview and the publisher's access at publish, and permits only the bindings declared by the exact running version. The App never receives a Core API key, datasource password, or connection secret.

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 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.

These governed capabilities are available to App server code:

CapabilityBinding it usesWhat it does
data.querydataReads rows from a selected dataset with governed fields, filters, sorting, and paging.
dashboard.embeddashboardMints a short-lived secure URL for the bound dashboard. The App never sees dashboard ids or entitlement filters.
workspace.embedworkspaceMints a short-lived Agentic BI workspace URL over the datasets the connection allows. Its lifetime is 2 to 30 minutes, 10 by default.
http.requesthttpCalls the connection's base URL with a method the connection allows. Knowi injects the stored credential; redirects are not followed and only public hosts are reachable.
state.get / state.setNoneReads and writes small App-scoped JSON values, up to 8 KB per key, 128 keys, and 256 KB per App. Use Managed PostgreSQL for anything larger.

A dashboard embed URL defaults to a 30-minute lifetime and can be minted for as long as the App session lasts. Outbound http.request bodies and responses are capped at 8 KB each.

data.query applies filters and sorting inside Knowi, before rows reach the App. For example, an App server route can request only the fields and rows it needs:

const page = await invoke(req, "data.query", {
  binding: "sales-orders",
  fields: ["Order Date", "Region", "Revenue"],
  filters: [{field: "Region", operator: "eq", value: "West"}],
  sort: [{field: "Order Date", direction: "desc"}],
  limit: 1000,
  offset: 0
});

Filter operators are eq, neq, gt, gte, lt, lte, isNull, and isNotNull. Combine gte and lte filters for a range. Field names must come from the selected dataset. A direct dataset's declared runtime tokens may also be passed as eq filters using the exact runtime-token name shown in its binding metadata. The response contains columns, row arrays in rows, and truncated. When truncated is true and nextOffset is present, use that exact offset for the next request. Knowi always adds the effective viewer's customer, group, user, shared, and macro content filters; App filters can narrow that authorized result but cannot replace those rules.

The default limit is 1,000 rows and the maximum is 200,000. Large or wide results may reach the response-size limit first; in that case, continue from nextOffset rather than increasing the limit.

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. In Knowi sign-in mode, governed reads use the previewing editor's current Knowi identity; Public and App-managed previews exercise the anonymous boundary used by their live mode. Mutating capabilities may return an explicit dry-run result 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. Every App is served at https://<slug>.apps.knowi.com, and you can also attach your own domain; see Custom domains. Renaming an App changes only its display name; its slug and URL remain stable. Removing an App requires typing its slug and takes the live App offline immediately; its versions and history are retained so an administrator can recover it. Source history remains in the repository, though a Knowi-managed repository is archived once no App still uses it.

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.

Custom domains

Every App is served at https://<slug>.apps.knowi.com. You can also attach one domain you own, such as oaklandcw.com or app.oaklandcw.com; the Knowi URL keeps working alongside it.

  1. In the Knowi Apps list, open the row's ... menu, select Edit app, and find the Custom domain section. Enter the domain (any scheme or path is stripped) and select Save.
  2. Prove ownership. Add a DNS TXT record at _knowi-verify.<domain> with the value shown in the dialog, then select Verify. The status changes from Pending verification to Verified. DNS propagation can take several minutes; select Verify again if it fails.
  3. Point the domain at Knowi. Add a CNAME record for the domain with the value domains.apps.knowi.com.
TypeNameValue
TXT_knowi-verify.<domain>The verification token shown in the dialog
CNAME<domain>domains.apps.knowi.com

After verification, a published App is republished automatically so it answers on the domain, and a TLS certificate is issued through Let's Encrypt within a minute or two. Until then, browsers may show a certificate warning. If the App is not published yet, the domain takes effect on the next publish. Knowi sign-in works on the custom domain; the login page is served on the App's domain and sessions are per domain. Preview URLs (preview-<slug>.apps.knowi.com) never use the custom domain.

Apex domains: A root domain such as oaklandcw.com cannot use a CNAME record. Where your DNS provider supports CNAME flattening or ALIAS/ANAME records (Cloudflare, DNSimple, NS1, and similar), point one at domains.apps.knowi.com. On Route 53 or other providers without that option, attach a subdomain such as www.oaklandcw.com with a CNAME and redirect the root to it, or contact Knowi support for an A-record target.

Changing or removing: Change replaces the domain and issues a new verification token, so repeat the TXT verification for the new domain. Remove detaches the domain; the App stops answering on it as soon as the republish completes, and the Knowi URL keeps working.

Limits:

  • One custom domain per App, and a domain can be attached to only one App across all Knowi accounts. A domain saved but left unverified for 72 hours can be claimed by another App, which removes it from yours; verify promptly or save it again when you are ready.
  • Domains under apps.knowi.com or knowi.com, and IP addresses, are rejected.
  • Saving a domain requires App edit permission. On a live App, verifying the domain, or changing or removing a verified domain, also requires publish permission because the live App is republished.
  • On-premises deployments must configure the Knowi Apps runtime with a certificate issuer (KNOWI_APPS_K8S_CUSTOM_DOMAIN_ISSUER). Otherwise, verifying the domain on a live App shows an error that includes "Custom domains are not enabled on this runtime", the domain stays in Pending verification, and the App keeps publishing normally on its Knowi URL; saving alone never contacts the runtime. Contact your Knowi administrator.

Share an App

An App is a shared Knowi asset, like a dashboard or a dataset. In the Apps list, open the row's ... menu and select Share to give other Knowi users and groups access. Sharing controls who can find and manage the App inside Knowi; it does not change who can open the live App, which the access mode decides.

Full access lets the recipient edit the App, subject to their own Knowi Apps permissions. Lower access levels are view-only: the App appears in their list, but the row menu, generation, and publishing are not offered.

New Apps are shared automatically with the creator's auto-share groups, if any are configured. An App you do not own and that is not shared with you does not appear in your list, including for administrators.

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, back up, test, and revoke storage from the App's Database panel.

Choosing a different storage option only stages the change. Nothing is created or revoked until you select Apply storage change; Cancel discards it. The panel then shows the live status - Provisioning, Ready, Revoking, Retained, or Action required - along with the applied schema version.

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.

Backups: select Back up now on a Ready database to take one on demand, where the operator has backups enabled. Knowi also takes a backup automatically before revoking a database and before removing an App, and stops the operation if that backup fails.

Retention: revoking removes the App's runtime credential but does not delete the data immediately. The panel shows the date after which retained data is scheduled for deletion, 30 days by default unless the operator sets another window. Back the data up or provision again before then. Retained data is never part of App source or releases.

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.

Knowi sign-in required is available only when the account can issue Knowi sign-in sessions. If it is greyed out, either the deployment does not have App sign-in enabled or the account has no SSO key; generate one under Customer Settings. New Apps default to Public while it is 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.

An explicitly selected dataset can be used by a Public or App-managed App through an App-level grant. That grant is rechecked against the publisher's current dataset access and content filters, but it does not apply each visitor's Knowi permissions or row-level rules. Treat the selected dataset as data the App may expose to every visitor allowed by its own access mode. Private dashboard bindings require Knowi sign-in.

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 or the explicit App-level dataset grant described above. 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.

Sign-in branding

A Knowi sign-in App can brand its own hosted sign-in and MFA pages so the login looks like the App instead of like Knowi. The branding is declared in the source manifest, under branding in app.json, and is stored with the built version, so each version keeps the branding it was built with.

KeyValue
nameDisplay name on the sign-in page, up to 80 characters.
logoRepository path to an SVG, PNG, JPEG, or WebP file no larger than 64 KB, usually a brand asset under web/assets/.
colorsAny of background, surface, text, muted, border, button, and buttonText, each a 3- or 6-digit hex value such as #0b1b2b.

Branding is validated strictly: an unknown key, a malformed color, or a logo that is oversize or not an image fails the build rather than shipping an unbranded page. AI writes branding when you describe it, and picks the logo from the brand assets attached to that request. A later change that attaches no new logo keeps the one the App already has; replace a logo by attaching another brand asset and naming it.

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 hiddenConfirm the account has AI Agents access, then ask 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.
A custom generation model is unavailableAsk an administrator to add that provider's API key or clear the App Generation selection under AI Settings to let Knowi choose the default frontier model.
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.
Custom domain stays in Pending verificationConfirm the TXT record is at _knowi-verify.<domain> with the exact value shown in the dialog, wait for DNS propagation, then select Verify again. Changing the domain issues a new token.
Custom domain shows a certificate warningConfirm the CNAME (or ALIAS/ANAME for a root domain) points to domains.apps.knowi.com. The certificate is issued within a minute or two of verification.
Error includes "Custom domains are not enabled on this runtime"On-premises only; raised when a live App is republished on the domain. The domain stays in Pending verification and the App keeps publishing normally on its Knowi URL. Ask a Knowi administrator to configure the Knowi Apps runtime with a certificate issuer (KNOWI_APPS_K8S_CUSTOM_DOMAIN_ISSUER), then select Verify again.
An image is rejected on uploadDesign references accept PNG, JPEG, or WebP up to 4 MB; brand assets also accept SVG but cap at 1 MB. The extension must match the real image type, a PNG must be within 4,096 px per side and 12 megapixels, and an SVG must contain no script, event attributes, javascript: URL, or <foreignObject>.
No room for another imageAn App holds up to 12 unused images totaling 24 MB. Remove one that no generation has used, or generate to consume the ones already attached.
A design reference cannot be removedA generated version already uses it. It stays listed; its bytes were discarded when that version was created.
The App still shows an old logoBrand assets stay in the repository. Attach the replacement as a brand asset and name it in the change so the source and, for a Knowi sign-in App, branding.logo point at the new /assets/<name> path.
Knowi sign-in required is greyed outEither the deployment does not have App sign-in enabled or the account has no SSO key. Generate one under Customer Settings, or ask a Knowi administrator.
Sign-in branding does not appearBranding applies only to Knowi sign-in Apps and only from the published version's app.json. Confirm the build succeeded and republish after changing it.
Storage change does nothingThe option is only staged. Select Apply storage change to provision or revoke, or Cancel to discard it.
An App is missing from the listApps appear only for their owner and for users they are shared with, administrators included. Ask the owner to share it.
AI edit conflictsRefresh and request the change again from the latest version.
Generation failsRead the safe failure reason shown with the job. Correct the request or source-contract issue, then retry the failed change when it is marked retryable.
A governed data call failsConfirm that the exact binding key is declared in this version's app.json, the asset still exists, and the editor or publisher still has access. Rebuild and publish after changing the manifest.
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.