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. 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 users 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 someone 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 or flagged files present: If the check detects a proxies.yml (outbound API declarations) 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 endpoints are summarized 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 detect proxies or flagged files, there is no file-review step. Continue with the install summary and confirmation.
4. Review the summary (Display Name, ID, Version, Author, and declared external endpoints).
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.

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. User configurations carry over seamlessly.
• 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.

Roles, Permissions, and Governance ​

The App Platform (Preview) uses your Organization’s standard Cribl RBAC. The subsections below describe who can create, install, and run Apps today. Per-App roles and sharing controls are planned for a future release. 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.

Members with product Editor roles (for example, Stream, Search, or Edge Editor) do not receive App creation rights through those roles alone.

Who Can Install and Manage Apps ​

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

Who Can Run Installed Apps ​

Any Member who can see an App in the Apps list can launch that App. Per-App access control (limiting which Members or Teams can open a specific installed App) is not available in this preview. Until then, assume any Member who can browse Apps can run every installed App.

How API Access Works When Someone Runs an App ​

When a Member runs an App, calls to documented Cribl APIs run under that person’s identity and assigned roles. The App does not elevate privileges. If a Member cannot perform an operation in the Cribl UI, the App cannot perform it on their behalf.

For patterns to handle permission errors in App code, see Permissions and execution context on the App Platform overview and Permissions and access in the Builder Guide.

Multiple App Builders in Your Organization ​

If people who are not production Administrators need to build Apps, use a dedicated App development Workspace with non-production data. Grant those builders Workspace Administrator 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 users 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 the App Platform (Preview) is available to your Organization is governed by the same license limits and feature gates described in App building blocks on the App Platform 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.

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 Package, version, and deploy in the Builder Guide).
3. An Administrator imports that package into the staging Workspace and completes any Review app’s file contents steps. Configure App Settings for staging endpoints and secrets.
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 ​