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.
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:
| Permission | Allows |
|---|---|
apps:edit | See Knowi Apps, create, describe changes, generate, build, and manage App settings. |
apps:publish | Publish a Ready version, roll back, and apply a live access or custom-domain change. |
apps:delete | Remove an App. |
apps:share | Share an App with other Knowi users and groups. |
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.
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.
Two buttons sit under the prompt box. You can also drag images onto the composer.
| Button | What it is | Accepted | What happens to it |
|---|---|---|---|
| Add design reference | A mock, screenshot, or style sample showing the look you want. | PNG, JPEG, or WebP up to 4 MB | Shown to the model while it writes this draft, then discarded. It never enters the repository. |
| Add brand asset | A logo or image the App itself should display. | PNG, JPEG, WebP, or SVG up to 1 MB | Committed 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.
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, optionally supplies the complete dataset/dashboard selection, 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.
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.
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, 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:
| Capability | Binding it uses | What it does |
|---|---|---|
data.query | data | Reads rows from a selected dataset with governed fields, filters, sorting, and paging. |
dashboard.embed | dashboard | Mints a short-lived secure URL for the bound dashboard. The App never sees dashboard ids or entitlement filters. |
workspace.embed | workspace | Mints a short-lived Agentic BI workspace URL over the datasets the connection allows. Its lifetime is 2 to 30 minutes, 10 by default. |
http.request | http | Calls 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.set | None | Reads 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.
| 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. 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.
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.
_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.domains.apps.knowi.com.| Type | Name | Value |
|---|---|---|
| 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:
apps.knowi.com or knowi.com, and IP addresses, are rejected.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.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.
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.
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. |
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.
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.
| Key | Value |
|---|---|
name | Display name on the sign-in page, up to 80 characters. |
logo | Repository path to an SVG, PNG, JPEG, or WebP file no larger than 64 KB, usually a brand asset under web/assets/. |
colors | Any 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 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 | Confirm the account has AI Agents access, then 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. |
| A custom generation model is unavailable | Ask 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 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. |
| Custom domain stays in Pending verification | Confirm 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 warning | Confirm 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 upload | Design 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 image | An 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 removed | A generated version already uses it. It stays listed; its bytes were discarded when that version was created. |
| The App still shows an old logo | Brand 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 out | Either 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 appear | Branding 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 nothing | The option is only staged. Select Apply storage change to provision or revoke, or Cancel to discard it. |
| An App is missing from the list | Apps appear only for their owner and for users they are shared with, administrators included. Ask the owner to share it. |
| AI edit conflicts | Refresh and request the change again from the latest version. |
| Generation fails | Read 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 fails | Confirm 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 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.