Installations

The Installations screen lets you install a marketplace pack in an environment (preflight, approval by other people, then apply), then upgrade it, roll it back, authorize a permission, suspend, resume or uninstall it, and read its events and supervision. Portal path: /marketplace/installs; its page title is Pack installations. It is used by the tenant administrators (tenant_admin); security officers suspend and resume installations.

What the screen shows

At the top, the install rule: "Install: preflight, then an approval decided by other people in the approvals inbox, then Apply. Approvers already recorded show in the details."

An Installations table with the filter Environment (dev, test, staging, prod) and Filter, then Refresh and Install a pack:

Column	Content
Package	Name of the pack.
Version	Installed version.
Environment	Target environment.
Status	pending_approval, installed, suspended, failed or uninstalled.
Granted permissions	Permissions granted to the pack.
Installed by	Author of the install.
Installed	Install date.

A click on a line opens a side panel with the installation read from the API. The list is read in one call. Empty state: No installation, "Start the install wizard: preflight, approval, then apply."

Actions

Each row action is shown only in the state given in the table.

Button or action	What it does	API call	Roles
Opening the screen, Environment then Filter	Reads the installations, optionally of one environment.	GET /v1/marketplace/installations	Member of the tenant
Install a pack then Create	Form Package, Version, Environment (required), Approved permissions (for example rag:query, tools:invoke), Configuration (JSON), Secret references (JSON). Runs the preflight and opens a four eyes approval; the installation is pending_approval.	POST /v1/marketplace/installations	tenant_admin
Click on a line	Opens the detail panel (approvers included).	GET /v1/marketplace/installations/{id}	Member of the tenant
Apply (state pending_approval)	Browser confirmation, then applies the approved install.	POST /v1/marketplace/installations/{id}/apply	tenant_admin
Upgrade (state installed)	Dialog Version (required), Approved permissions, Configuration, Secret references; shows the answer.	POST /v1/marketplace/installations/{id}/upgrade	tenant_admin
Roll back (state installed)	Destructive confirmation, then returns to the previous version.	POST /v1/marketplace/installations/{id}/rollback	tenant_admin
Uninstall (any state but uninstalled)	Destructive confirmation, then uninstalls the pack.	POST /v1/marketplace/installations/{id}/uninstall	tenant_admin
Events	Shows the events of the installation.	GET /v1/marketplace/installations/{id}/events	Member of the tenant
Supervision	Shows the activity, quality, costs and incidents of the installed pack.	GET /v1/marketplace/installations/{id}/supervision	Member of the tenant
Authorize a permission (state installed)	Dialog Permission (required, for example tools:invoke); shows whether the pack may use it.	POST /v1/marketplace/installations/{id}/authorize	Portal: tenant_admin; server: tenant_admin, developer, agent, service
Suspend (state installed)	Dialog Reason (required), Permissions (suspend only some capabilities); immediate.	POST /v1/marketplace/installations/{id}/status	tenant_admin, security_officer
Resume (state suspended)	Dialog Approval, Reason; resuming goes through a four eyes approval.	POST /v1/marketplace/installations/{id}/status	tenant_admin, security_officer

Roll back and Uninstall use the destructive confirmation, which reads GET /v1/lineage/graph to list the impact.

Roles

From services/control-plane/src/eai/domains/marketplace/routes.py: reading needs a principal inside a tenant; install, apply, upgrade, rollback and uninstall require ADMIN_ROLES (tenant_admin); suspend and resume require TRUST_ROLES (tenant_admin, security_officer); authorize requires RUNTIME_ROLES. platform_admin passes every check. The portal hides each action for the roles of ROLES.marketplaceInstallers or ROLES.marketplaceAdmins of portal/src/lib/kit.ts.

warning

Roll back and Uninstall change what the agents of the environment can call. Read Supervision first and run them in prod only in a change window.

Typical tasks

Install a pack in production

1. Request the install. Button Install a pack: Package, Version, Environment prod, Approved permissions, Configuration, Secret references (references to secrets, never the values), then Create. Expected result: a line in state pending_approval. If it fails: preflight_failed (HTTP 422) lists the failed checks; installation_exists (HTTP 409) when the pack is already installed in this environment.
2. Have it approved. Other people decide the request in Approvals inbox. Expected result: the approvers show in the detail panel. If it fails: the request stays pending until the quorum is reached.
3. Apply. Row menu > Apply, accept the confirmation. Expected result: the state installed. If it fails: installation_state (HTTP 409) when the installation is not in the expected state.

Upgrade, then roll back if needed

1. Upgrade. Row menu > Upgrade, Version of the new release, submit. Expected result: the answer of the upgrade in a side panel. If it fails: installation_state (HTTP 409) when the version is the same or the state is not installed.
2. Watch it. Row menu > Supervision. Expected result: activity, quality, costs and incidents. If it fails: read Events.
3. Roll back when it misbehaves. Row menu > Roll back, confirm. Expected result: the previous version is back. If it fails: rollback_unavailable (HTTP 409) when there is no previous version.

Contain a pack during an incident

1. Suspend. Row menu > Suspend, Reason, optionally the Permissions to cut. Expected result: the state suspended at once. If it fails: forbidden when you are neither tenant_admin nor security_officer.

Troubleshooting

Symptom	Cause	Fix
preflight_failed (HTTP 422)	A check of the preflight failed.	Run the preflight of the Pack catalog and fix the failed checks.
installation_exists (HTTP 409)	The pack is already installed in this environment.	Upgrade the existing installation.
installation_state (HTTP 409)	The action does not fit the current state.	Read Status and the details; follow the order install, apply, upgrade.
rollback_unavailable (HTTP 409)	No previous version to return to.	Uninstall, or upgrade to a fixed version.
permission_not_requested / permission_not_granted (HTTP 422)	The permission is not declared by the pack or not approved.	Upgrade with the permission in Approved permissions.
permission_unsafe (HTTP 403)	The permission is refused by the platform.	Remove it from the request.
package_suspended (HTTP 409)	The pack is suspended in the catalog.	Resume the pack in the catalog first.
config_invalid (HTTP 422)	Configuration does not match the schema of the pack.	Correct the JSON.

Related pages

• Marketplace guide
• Pack catalog
• Change pipeline
• Approvals inbox
• Licence and support