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. When you have permission to create Apps and temporary Apps from local development exist (for example Live Preview scaffolding), the page shows 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. Delete those entries from this tab. Use Installed to upgrade Apps or open App Settings.

When no Development Apps are registered, or you do not have permission to create Apps, you see the installed Apps list directly without tabs.

Organization administrators install, upgrade, and remove Apps. Members open Apps they are allowed to run from the Installed inventory.

Install an App ​

As an administrator, you can install Apps in these ways:

• Cribl Marketplace: Install an App from the in-product catalog. See Install from the Cribl Marketplace.
• Import through Add App: Install a custom .tgz or a package from a URL or Git repository. See Import Through Add App.
• Deploy from Live Preview: A builder with a local development App uses Deploy in Live Preview to install into the Workspace where they are previewing. See Deploy from Live Preview.
• Terraform: Use the criblio_app resource to install from Git, a file, or a URL, or to create a minimal App scaffold. See the provider example.

Review App Capabilities ​

Cribl summarizes what an App declares, so that you can assess it before you approve an install and review it again later. A summary covers the Cribl API permissions the App requests, its backend functions, and the external hosts it reaches. Per-App App Settings also covers schedules. During install review, the summary includes executable files Cribl flagged in the package.

Each summary opens with a plain-language statement built from those declarations. Read the statement first, then select a count card to review the corresponding details:

• Permissions: Declared Cribl API permissions.
• Backend Functions: Declared functions. When schedule information is available, the card also shows how many functions run on a schedule.
• Schedules: Declared schedule IDs, functions, cron expressions, and body expressions. This card appears only in per-App App Settings.
• External API Access: External hosts the App can call. Before installation, these are the hosts the package declares. After installation, the tab also includes hosts an administrator authorized. See External API Access Tab.
• Flagged Files: Executable files the pre-install check found in the package.

Keep these limitations in mind:

• The summary reports what an App declares, not what it does at runtime. Before you rely on an App in production, compare its declarations against live traffic. See Observe API and Proxy Traffic During Validation.
• Schedule information is not available during the pre-install check. As a result, Review App does not identify scheduled functions. Review schedule information on the Cribl Marketplace detail page before installation. After installation, use App Settings > Backend Functions for a summary or Schedules for complete details.
• Flagged Files appears only in Review App, because only the pre-install check examines the package contents.

Install from the Cribl Marketplace ​

The Cribl Marketplace is the in-product catalog of published Apps built by Cribl and the community.

For how App builders submit Apps to the catalog, see Publish an App to the Cribl Marketplace.

1. Open an App in the Cribl Marketplace. Review the capability summary on Overview, then select its cards to open the available capability tabs. See Review App Capabilities.
2. Select Install. Cribl runs pre-install checks. You already reviewed the App’s declarations on the detail page, so the Review App modal opens only for flagged executable files. In that case, it shows only those files.

Cribl shows an App as already installed from the Cribl Marketplace only when the App ID matches (case-insensitive) and that ID was installed from the catalog. The same ID installed from a file or URL is tracked separately.

If the App ID is already in use, install fails with HTTP 409. Upgrade the App or remove the conflicting install first.

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:
   • Capabilities or flagged files present: The check might find declared outbound hosts (proxies.yml), declared in-product API permissions (for example policies.yml), declared backend functions, or flagged executable files. If it does, the Review App modal shows a capability summary and a tab for each finding. Review the details, then confirm that you accept the App. See Review App Capabilities.
   • None of those findings: If the check does not surface material that requires review, there is no Review App step. Continue with the install summary and confirmation.
4. Review the install 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 Live Preview ​

When a builder selects Deploy in Live Preview, Cribl packages the local development App. It then installs that package into the Workspace where Live Preview is running. That path does not run the same pre-install file review as Add App > Import. You are installing a bundle built on the builder’s machine. If the App declares backend functions, Cribl starts deploying them after Deploy returns. See Backend Deployment Status.

Other members cannot open the deployed App until you assign the App user access level. See Share Access to Installed Apps.

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.
• A nonempty backend.yml must declare at least one valid backend function. Each declared script must exist in the package, use a path that stays inside the App, and not exceed 5 MB.

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 modal behavior apply to the upgrade package as to Add App > Import. Installs from the Cribl Marketplace follow the narrower review described in Install from the Cribl Marketplace.

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

License Limits ​

Installing or upgrading an App that declares backend functions or outbound hosts requires an Enterprise license/plan. Saving hosts on App Settings > External API Access also requires an Enterprise license/plan.

Without an Enterprise license/plan, Cribl blocks installation and upgrade of an App that declares backend functions or outbound hosts, and blocks saving hosts on External API Access. When Cribl blocks an upgrade, the installed App version stays unchanged. Live Preview can still run backend functions and outbound hosts.

A Free or Standard plan can install an App that does not declare backend functions or outbound hosts.

Backend Deployment Status ​

Installing an App, upgrading it, or selecting Deploy in Live Preview can start a backend deployment for Apps that declare backend functions. That deployment continues after the install, upgrade, or Deploy action finishes.

Cribl reports backend deployment status in the Apps inventory:

• Deploying… means the deployment was submitted or is in progress. Cribl refreshes in-progress status while you remain on the page.
• Error means the deployment failed. Select the status to review the reported reasons.
• No backend status appears after a successful deployment or for an App without backend functions.

When you open an installed App whose backend is still deploying, Cribl shows We’re setting up your App instead of the App UI. The page updates automatically when deployment succeeds, or you can select Refresh App to check again.

If deployment fails, Cribl shows App failed to deploy, the reported failure reason, and Redeploy instead of the App UI. Select Redeploy to retry the backend from the currently installed package. The App UI remains unavailable until the deployment succeeds. Users without permission to deploy Apps see the failure but not the Redeploy action.

Live Preview is the exception: it keeps the App UI open while its backend deploys, so no deployment screen appears there. While Cribl packages and installs the App, Live Preview shows a Deploying app… notification and keeps Deploy pending. Track the backend deployment itself from the App’s row in the Apps inventory. To retry a failed backend, select Deploy again in Live Preview, or open that App from the Apps inventory to use Redeploy.

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.

Configure Organization App Settings ​

Use Settings > Global Settings > App Settings to turn Apps on or off for the Organization and configure App backend and scheduling limits. This page is separate from per-App App Settings (see Manage App Settings).

1. Select Settings > Global Settings > App Settings.
2. Confirm that Enable Apps is toggled on. It is on by default. When you toggle it off, Cribl does not register the Apps routes.
3. Configure these limits as needed:
   • Maximum concurrent backend function executions: Concurrent backend function invocations across all Apps on the Leader. The default is 100. Additional requests receive an HTTP 429 response when the Leader reaches the limit.
   • Leader requests limit: Maximum Leader API requests each App backend can make per minute. The default is 50, and the allowed range is 1 through 1,000.
   • Scheduled Jobs: Maximum schedules per App. The default is 25, and the allowed range is 1 through 100.
   • Payload expression size per request: Maximum length of a schedule’s bodyExpression, in characters. The default is 4,096, and the allowed range is 1 through 16,384.
   • Job Concurrency: Maximum concurrent scheduled jobs across all Apps on the Leader. The default is 50, and the allowed range is 1 through 100.
4. Select Save, then confirm the server restart.

Changes take effect after the Leader restarts.

Manage App Settings ​

Per-App App Settings is where you review an installed App’s metadata and capabilities, manage its KV store, and authorize external hosts. 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. General opens by default. Key-Value Stores, Permissions, and External API Access are always available. Backend Functions and Schedules appear when the App declares backend functions. See Review App Capabilities.

The General tab includes the capability summary. Select a card to open the corresponding capability tab.

General Tab ​

The General tab lists read-only fields for the installed App:

• App ID, Display Name, Description, Author, and Version come from the installed package. App builders set these in package.json. To change them after install, package a new release and upgrade the App.
• Source shows how you installed the App: File for Import from File, Cribl Marketplace for Marketplace installs, or the URL or package file name for other Add App import paths and Deploy from Live Preview. Upgrade or reinstall the App to change it.

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, clone, or delete: Manage existing keys from the Actions (...) menu on each row.

Edit opens an existing pair so you can change it. Clone starts a new pair from an unencrypted one. Give the clone a unique Key before you save. Saving with the original key overwrites that entry. Clone does not appear for encrypted entries, because the stored value is redacted and cannot be copied. Delete removes the pair after you confirm.

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.

Backend Functions Tab ​

1. Open App Settings as described above.
2. Select Backend Functions.

This read-only tab appears only when the App declares backend functions. Each row shows the function name, a description when provided, and a Scheduled tag when a schedule invokes that function. To change what the App ships, install a new package. See Backend Functions in the Builder Guide.

Schedules Tab ​

The read-only Schedules tab appears when the App declares backend functions, even if it declares no schedules. When the App has schedules, the table lists:

• Schedule ID
• Function
• Cron (UTC)
• Body Expression (a dash when the App omits one)

When the App declares no schedules, the tab shows an empty state.

Use Backend Functions to see which functions are scheduled. Use Schedules to inspect when and how each scheduled invocation runs. The tab does not provide controls to create, edit, pause, enable, disable, or delete schedules. A declared schedule runs according to its cron expression. To change package-declared schedules, install a new package. Authorized callers can also create, update, and delete schedules through the App-scoped Schedule API. App builders declare package schedules in config/schedules.yml. See Schedule a Backend Function in the Builder Guide.

External API Access Tab ​

Use this tab to see every external host the App is allowed to call, and to authorize hosts the App package does not include.

An App builder declares the hosts an App always needs in proxies.yml. They cannot know the domains that are specific to your Organization, such as your own identity provider tenant. Rather than waiting for the builder to ship a new package for each customer, authorize those hosts yourself after install. Because this is an administrator surface, an App can never widen its own external access.

To add a host, open External API Access, add an object to the array the editor already shows, and select Save. Do not replace the array with only the new host:

{
  "id": "login.okta.com",
  "timeout": 15000,
  "paths": {
    "allowlist": ["/"]
  }
}

Each entry’s id is the hostname. The remaining fields are the same declarations App builders use in proxies.yml; see External APIs and proxies.yml in the Builder Guide for timeout, path, and header rules.

Keep this in mind as you edit:

• Editing requires the same permission as Create App. Other administrators can open the tab but cannot change it.
• Save writes the array as the administrator-managed hosts. To drop a host you added earlier, delete its entry and save. Hosts that shipped in the App package stay in effect even if you omit them. If you delete a packaged host, it returns after you save. To remove a packaged host, ask the App builder for a new package.

To manage the same configuration outside the UI, use GET and PUT /api/v1/apps/{id}/proxies. GET returns every host currently in effect. PUT replaces only the administrator-managed hosts with the items array you send. Packaged hosts remain if you omit them.

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 declared hosts, paths, and options on every request:

• Declared hosts only: Outbound calls succeed only for the hosts packaged in proxies.yml plus the hosts you authorize on App Settings > External API Access. The request path and options must also match those declarations. Requests to any other host 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 declared hosts. 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 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 Live Preview. 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 General, Key-Value Stores, Permissions, Backend Functions, Schedules, and External API Access). Treat installs and upgrades as privileged changes that can affect Organization data, backend functions, and outbound integrations. Authorizing external hosts on External API Access requires the same permission as Create App.

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.

Share Access to Installed Apps ​

Use Share to choose which members and teams can open an installed App:

• App user: The member or team can open and run the App. The App user access level does not grant other Cribl administrator permissions.
• No access: The App does not appear for the member or team.

A newly installed App stays hidden from other members until you assign the App user access level. Upgrade keeps the existing Share assignments.

An App that every member can already open stays visible after Upgrade. Deploy, or saving Share, limits the App to members and teams who have the App user access level. To keep the existing members and teams, upgrade with a .tgz instead of using Deploy.

Organization administrators, and other roles with permission to update App access, assign the App user access level or No access as follows:

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. On the Members and Teams tabs, assign the App user access level or No access, then save.

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 ​

Calls from the App UI run under the signed-in member’s identity and assigned Stream, Edge, Search, and Lake roles.

If a member cannot perform an operation in the standard Cribl UI, the App UI 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.

Backend functions use the App-wide grants declared in policies.yml, not the invoking member’s product roles. The caller’s user ID is available to a function for attribution only. See Cribl APIs and Identity.

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 and outbound proxy paths, and its backend function endpoints.

It does not replace product RBAC. Calls from the App UI to general Cribl REST APIs are still authorized as they are 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 as part of install or 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.

Backend functions and outbound hosts follow the license limits. You can leave Apps 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 ​

Before installation, review the App declarations through the applicable install flow. Use those declarations as the baseline for validating live behavior after installation.

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, AGENTS.md, CLAUDE.md, files under config/, and backend source under backend/.
• 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 or External API Access 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, KV edits, and External API Access updates 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.

• Backend function logs: Output from console calls in backend functions appears in app-backend.log. After that log exists, Monitoring > Logs includes Leader > Apps in the log picker. Select All Apps to search the shared log, or select an installed App to apply its cid filter automatically. Use the endpoint and invocationId fields to isolate one function or invocation.

• 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 ​