Preview Feature ​

This Preview feature is still being developed. We do not recommend using it in a production environment, because the feature might not be fully tested or optimized for performance, and related documentation could be incomplete.

Please continue to submit feedback through normal Cribl support channels, but assistance might be limited while the feature remains in Preview.

Learn how to install, upgrade, remove, and govern Apps in your Organization, as well as how to configure App settings and monitor behavior. Before you roll an App out broadly, complete Observe API and Proxy Traffic During Validation in a non-production Workspace. For how App builders package Apps and declare external APIs, see the Builder Guide.

The App Management UI ​

To manage Apps, navigate to Apps from the top bar. This page can display two tabs:

• Installed: Apps that have been packaged and deployed. These are the Apps that members interact with and run.
• Development: Temporary Apps from local development (for example, Live Preview scaffolding). Delete those entries from this tab. Use Installed to upgrade Apps or open App Settings.

Install an App ​

Apps are distributed as .tgz packages. Install them by import through Add App (for example a file a colleague shared). Or use Deploy from the Create App wizard when you package and upload your own build from your machine.

Import Through Add App ​

Use Add App > Import from File when you have a .tgz from an App builder. If your Organization hosts packages internally, you can also use Import from URL or Import from Git when those options are enabled.

1. Select Add App > Import from File (or Import from URL / Import from Git when available).
2. Choose the .tgz package.
3. Cribl runs a pre-install check on the archive. How the flow continues depends on what the check finds:
   • Proxies, declared API permissions, or flagged files present: If the check detects a proxies.yml (outbound API declarations), policy metadata in the bundle that declares additional in-product API permissions the App expects (for example policies.yml from the authoring template), or other flagged file content, the UI opens a Review app’s file contents modal. You must review what the App contains and confirm that you accept it before the install can finish. Declared external hosts, declared in-product API permissions, and other summarized material are shown for you. If the App includes outbound calls that use large language models (LLMs), that is indicated explicitly so you can decide whether to proceed.
   • None of those findings: If the check does not surface material that requires review, there is no file-review step. Continue with the install summary and confirmation.
4. Review the summary (Display Name, ID, Version, Author, declared external endpoints, and any declared in-product API permissions shown for that package).
5. Confirm the import.

Deploy From Create App ​

When you Deploy from the Create App wizard, Cribl packages your local project and installs it in one step. That path does not run the same pre-install file review as Add App > Import. You are installing a bundle you built on your own machine.

Who can open the App after deploy: Treat Deploy like shipping a new install for the same App ID, not like the Upgrade action on an existing row. Members who could open the App only because it was easy for everyone in the Organization to discover might no longer see it under Apps > Installed until sharing is set again. People who already have App user for that App usually keep access, but Organization administrators should open Share after each Deploy and confirm the Members and Teams lists still match who should run the App. If you rely on broad discovery, prefer handing a .tgz to an administrator and using Upgrade on Installed (see Upgrade an App) so access rules carry forward the same way.

Each time you deploy, the UI shows a Confirm deploy modal with fixed (static) copy. You must acknowledge it before the deploy completes. The modal appears on every deploy.

Validation Checks ​

During import, Cribl validates the package. If a required check fails, the UI displays a descriptive error.

Archive and size limits:

• Compressed archive must not exceed 100 MB.

Security and contents:

• Symlinks, hard links, and path traversals (absolute paths, .. segments) are blocked.
• All extracted directories are forced to 0755 and files to 0644. Executable bits are stripped.

Metadata and configuration:

• package.json must include at minimum name and version, and mark the bundle as an App under cribl (for example, "cribl": { "type": "app" }).
• App ID must not conflict with any existing Pack or App name.
• proxies.yml (if present) must include required fields. Declared domains are not resolved at install time, and domain keys are not validated as IP literals during install. The server-side proxy middleware applies server-side request forgery (SSRF) protection and other access rules when the App makes outbound requests. SSRF protection blocks requests that would cause the proxy to reach unintended internal targets.

Upgrade an App ​

Upgrades are handled by installing a newer package for the same App ID.

1. In the App’s row, open the actions menu (three dots) and select Upgrade.
2. Upload the new .tgz package.
3. Review the version changes and confirm the upgrade.

The same pre-install check and Review app’s file contents modal behavior apply to the upgrade package as to Add App > Import.

Upgrade behavior:

• UI assets and App logic are replaced with the new version.
• KV store data and settings are preserved. Configuration saved through the App UI carries over seamlessly.
• Who may open the App from Apps > Installed stays aligned with Share as it was before the upgrade. Use Upgrade when you want a newer package without reworking who can discover and open that App row.
• Best practice: Test upgrades in a staging Workspace first, especially if release notes from the App builder indicate major version changes. See Development and Release Workflow for Customer Apps.

Delete an App ​

1. In the App’s row, open the actions menu and select Delete.
2. Review the confirmation details and confirm.

Delete behavior:

• The App UI, assets, and entry points are removed from the deployment.
• After delete, KV data and settings are removed with the App. Reinstalling starts with empty KV.

Manage App Settings ​

For how App code calls the KV API, encryption rules, and REST paths, see The KV Store in the Builder Guide.

Open App Settings from the Apps inventory row menu (Settings) or from the gear icon in the App toolbar. App Settings has two tabs: Key-Value Stores and External API Access. Organization-wide outbound policy is configured in External API Access.

Key-Value Stores Tab ​

1. Open App Settings as described above.
2. Select Key-Value Stores.

From this tab, you can:

• Seed configurations: Add initial settings JSON objects that the App needs on its first run.
• Store secrets: Add API keys and external tokens only as encrypted entries. Encrypted values are redacted in the UI and can only be referenced server-side. They are never exposed to the browser. Do not rely on plain KV values for credentials.
• Edit or delete: Modify or remove existing keys.

Quota: Each App can store up to 1,000 keys by default. If an App requires more, contact Cribl Support to request a quota increase.

External API Access Tab ​

1. Open App Settings as described above.
2. Select External API Access.

Use this tab to review how outbound calls to external APIs are governed for this App and your Organization. Default behavior and enforcement are described in External API Access.

External API Access ​

Apps can call external, third-party APIs through a server-side proxy. External API access is enabled by default for your Organization.

Cribl still enforces each App’s proxies.yml declarations on every request:

• Declared hosts only: Outbound calls succeed only for domains, paths, and options the App declares. Requests to hosts that are not declared in proxies.yml are blocked with a 403 response. Apps that only call Cribl APIs are unaffected.
• Secure handling: Allowed traffic uses the server-side proxy with SSRF protections, declared timeouts, and optional credential injection from KV so secrets are not exposed to the browser.

App state and Cribl API traffic remain within Cribl unless a developer configured outbound calls that persist data elsewhere. That behavior follows the App and its proxies.yml. Before you rely on an App in production, confirm declared hosts during import (see Install an App) and again on App Settings > External API Access. Then compare live traffic to those declarations in a non-production Workspace. See Observe API and Proxy Traffic During Validation.

Roles, Permissions, and Governance ​

Apps (Preview) uses your Organization’s standard Cribl RBAC for Stream, Edge, Search, and Lake APIs. For installed Apps, Cribl also enforces per-App access: you choose which members and teams may open each installed App. For a consolidated summary of where App code runs, how credentials and outbound calls are handled, and how that relates to these roles, see Runtime, Architecture, and Security.

Who Can Create, Preview, and Package Apps ​

Only Workspace Administrators can use Create App, Live Preview, and Deploy from the create wizard. These flows require the same privileges as installing an App because Live Preview registers a develop App in the Organization behind the scenes.

Product-level permissions for Stream, Edge, Search, or Lake–including Editor or Admin–do not grant Create App, Live Preview, or Deploy by themselves. Workspace Administrator in that Workspace is still required.

Who Can Install and Manage Apps ​

Only Organization administrators can install, upgrade, and delete Apps and can open App Settings (including the Key-Value Stores and External API Access tabs). Treat installs and upgrades as privileged changes that can affect Organization data and outbound integrations.

Who Can Run Installed Apps ​

• The Apps > Installed list shows only Apps your account may open. If you have no grant for an App, that App is hidden from your inventory.
• To use any App, you must still be an Organization member with access to at least one Cribl product (Stream, Edge, Search, or Lake). Per-App grants do not replace that membership requirement.
• The App user grant (see Share Access to Installed Apps) is scoped to a single installed App. It allows opening that App’s UI, its App-scoped key-value (KV) paths, and its App-scoped outbound proxy paths. It does not grant broader Cribl administrator capabilities.

Apps Installed Before Per-App Sharing ​

An App that was first installed in your Organization before Cribl began enforcing per-App sharing on Installed rows may still be visible to every member who could browse Apps.

That open visibility lasts until you take an action that applies governed defaults for that App ID. Publishing again with Deploy from the Create App wizard is one example of such an action; after that, expect the tighter pattern where Share controls who sees the App. See Deploy From Create App.

Share Access to Installed Apps ​

Organization administrators, and other roles your Organization grants permission to update App access control lists, assign who may open each installed App.

1. Open Apps > Installed.

2. For the App row, open the actions menu (three dots) and select Share. You can also open the installed App and select Share from the toolbar menu (three dots).

   Share is available only for rows under Installed. Entries on the Development tab from Live Preview do not support this flow.

3. In the sharing panel, assign App user or No access on the Members and Teams tabs, then save.

Cribl exposes one ACL template for shared App access (App user). It governs read and write inside that App’s UI, KV namespace, and proxy routes as implemented on the platform.

Removing App user, or setting No access, hides the App from that member’s or that team’s Installed list. Assigning App user restores visibility and the ability to run the App.

For how API calls behave once a member can open an App, see App User Grants and Product APIs.

How API Access Works When a Member Runs an App ​

When a member runs an App, calls to documented Cribl APIs run under that member’s identity and assigned Stream, Edge, Search, and Lake roles. The App does not elevate privileges beyond those roles.

If a member cannot perform an operation in the standard Cribl UI, the App cannot perform it on their behalf. For example, a Worker Group picker only lists groups that member may already see.

For patterns to handle permission errors in App code, see Permissions and Execution Context in this overview and Permissions and Access in the Builder Guide.

App User Grants and Product APIs ​

The App user grant adds a narrow policy template scoped to one App ID. It covers App delivery and App-scoped resources. Examples include metadata and UI bundle paths, that App’s KV API namespace, and that App’s outbound proxy paths as implemented on the platform.

It does not replace product RBAC. Any call your App makes into general Cribl REST APIs is still authorized the same way as in the main product UI.

When an App’s package declares additional in-product API permissions beyond what a bare App user grant implies, you review those declarations in the same Review app’s file contents flow as part of Add App > Import and Upgrade. If the author does not declare extra permissions, behavior falls back to each signed-in member’s normal Stream, Edge, Search, and Lake permissions for product APIs. Authors should declare everything the UI needs so members with App user but narrower product roles still get a consistent experience where the platform supports it.

This release focuses on governable visibility, per-member and per-team sharing, App-scoped access, and administrator review of declared product endpoints. It does not introduce an arbitrary matrix of custom per-App roles for every future edge case. Organization administrators continue to tune platform IAM separately.

Design and test with accounts that have realistic Stream, Edge, Search, and Lake roles, not only App user. You will see the same partial visibility and 403 responses that members will get when they run the App.

Multiple App Builders in Your Organization ​

If members who are not production administrators need to build Apps, use a dedicated App development Workspace with non-production data. Grant those builders the Workspace Administrator role in that Workspace only. Do not make every member an administrator in a production Workspace to enable App development.

Members in that dev Workspace can use Create App, Live Preview, and packaging workflows. An administrator still installs packages into Workspaces where members run the App, including production when you are ready.

For a recommended multi-Workspace promotion path, see Development and Release Workflow for Customer Apps.

Whether Apps (Preview) is available to your Organization is governed by the same license limits and feature gates described in App Building Blocks on the App overview. You can leave the feature disabled until you finish internal checks or policy reviews.

Development and Release Workflow for Customer Apps ​

Organizations that build their own Apps should treat each install as a release into an environment. Cribl does not provide a separate “staging mode” inside one Workspace. You promote a versioned .tgz package from Workspace to Workspace.

Dev, Staging, and Production Workspaces ​

Map Workspaces in your Organization to environments. At minimum, use separate Workspaces for development, staging, and production. Staging is where you validate an App with realistic configuration and data before Members rely on it in production. Use that Workspace (or another dedicated test Workspace) so you only promote behavior you have already checked.

Observe API and Proxy Traffic During Validation ​

When you import or upgrade through Install an App, you confirm the package in the UI (the install summary and any Review app’s file contents prompt). That review can include declared outbound hosts, declared in-product API permissions from the bundle, and proxy rules. Declared outbound hosts and proxy rules are also documented under External API Access and on App Settings > External API Access. Together they summarize outbound access and in-product permission declarations before anyone opens the App.

After installation, finish App Settings in a test Workspace. See Development and Release Workflow for Customer Apps and Manage App Settings. Sign in the way a production Member would (How API Access Works When a Member Runs an App). Then use Browser and Logs to capture live requests.

Browser: Open the App, then open Developer tools > Network. Filter to Fetch or XHR. Use the App through its main workflows. For each request, check status, path, and whether the volume fits the action you took.

Logs: Open access and error logs and apply the App filters from Monitoring, Logging, and Auditing. Compare that stream with what Network showed so you can explain behavior during support, security, or compliance reviews.

Recommended flow:

1. Build and iterate in the development Workspace (or on a developer machine with Live Preview bound to that Workspace).
2. Run npm run package to produce a .tgz with an explicit semantic Version (see 4. Package, Version, and Deploy in the Builder Guide).
3. An Administrator imports that package into staging and configures App Settings for that environment. Then complete Observe API and Proxy Traffic During Validation before importing the same .tgz into production.
4. After sign-off, import the same .tgz (same Version and App ID) into production. Use Upgrade in production only when you intend to move that environment to a newer package.

Each Workspace keeps its own installed App instance, KV data, and App Settings. Do not assume KV or secrets copied automatically from staging to production. Plan configuration per environment.

Version Control With Git ​

Keep App source code in Git so you can review changes, tag releases, and roll back. The installable artifact remains the .tgz produced by npm run package, not the Git tree itself.

Recommended practices:

• One repository per App (or a monorepo with a clear folder per App ID). Commit the scaffolded project, including package.json, proxies.yml, and AGENTS.md.
• Match Git tags to package versions. After you bump version in package.json and run npm run package, tag the commit (for example v1.2.3) so you can rebuild or audit that release later.
• Deploy a specific version to a specific Workspace by importing the .tgz built from that tag. Production and staging can run different versions at the same time because installs are per Workspace.
• Use branches for promotion intent. For example, merge to main only for releases you package for staging or production, and use feature branches for work in progress.
• Automate packaging in CI (optional). A CI job can run npm run package on tagged commits, store .tgz artifacts, and hand them to Administrators for Import from File (or Import from URL when your Organization hosts packages that way).

When your Organization enables it, Add App > Import from Git can install from a repository that contains a valid App package layout. Whether that option is available depends on Organization policy. File-based import remains the common path for customer-built Apps.

Monitoring, Logging, and Auditing ​

Combine audit events with access logs and Access and error logs when you monitor App usage. Audit surfaces show who installed, upgraded, or deleted Apps and who changed KV in App Settings. Structured logs capture App API and proxy traffic at runtime. Use the filters in this section to isolate traffic for a specific App.

Cribl provides built-in observability for App behavior:

• Audit events: App installs, upgrades, deletions, and KV edits appear in the standard Cribl audit surfaces, tracking who performed the action and when.

• Access and error logs: Cribl logs structured events for every API request made by an App. This includes proxy failures, KV quota issues, and validation errors.

• Filtering: Isolate App traffic using the App ID and log fields. App-originated requests also include a Cribl-App: <app-id> header on the wire.

  In access logs, combine these filters:

  • http_user_agent == "product-ui-app" to match requests from the embedded App UI.
  • cribl_app == "<installed-app-token>" to match a specific installed App. The token is built from the App ID and the installed package (for example cribl_app == "notebook-app-1-0-28-tgz" when the App ID is notebook-app).

  Adjust the cribl_app value to match the identifier for the App you are investigating.

Troubleshooting Quick Reference ​