System Apps
Platform-managed extensions that auto-install for every user, hide from the marketplace, and cannot be uninstalled
Some extensions are not "discovered and installed" — they are part of the platform. Admin, Billing, Developer Portal, and AI Cloud Agents (automations) all exist because Imperal Cloud provides them, not because the user opted in. Federal v4.2.0 codifies this as the system flag.
Who can use this
Only first-party Imperal authors can ship an extension with system=True. The Dev Portal enforces the author allowlist server-side at publish time. Validator V31 catches local mistakes before you waste an upload. Third-party developers should ignore this page — the normal marketplace flow is what you want.
Lifecycle
| Stage | System app | Regular app |
|---|---|---|
| Registration | Auto-installed for every new user | Not installed; user discovers via marketplace |
| Marketplace listing | Hidden from list/featured/categories/developer-profile queries | Visible |
| Sidebar | Appears in the bottom block as soon as the user lands on the panel | Appears in the middle scroll list only after explicit install |
| Uninstall | Forbidden — auth-gw returns 403 | Allowed via marketplace card |
The "auto-install" step writes a row into marketplace_installs with source='auto_system' at the same transaction that creates the user. If the system-app insert fails, the user-create transaction fails too — there is no "new user without billing" state.
Declaring a system extension
from imperal_sdk import Extension
ext = Extension(
"billing",
version="2.0.0",
display_name="Billing",
description="Imperal Cloud billing — usage meter, invoices, prepayments.",
icon="icon.svg",
actions_explicit=True,
system=True, # ← marks this as a platform-managed app
)The build emits "system": true at the top of imperal.json:
{
"manifest_schema_version": 3,
"sdk_version": "4.2.0",
"app_id": "billing",
...
"system": true,
...
}What stops abuse
Three layers — defence in depth:
SDK validator V31 (local)
imperal validate runs locally before you publish. If your IMPERAL_AUTHOR_ID environment variable is set and not in the first-party allowlist, V31 fails with a clear error.
✗ V31: Extension(system=True) is reserved for first-party Imperal extensions
(admin / billing / developer / automations). Author 'imp_u_dimas-...'
is not in the Imperal author allowlist.Dev Portal author check (server-side)
Even if you bypass the local validator, the Developer Portal looks up your registered developer record on upload and refuses to publish a manifest with system=True from a non-Imperal author. This is the authoritative gate.
Auth-gw RBAC (runtime)
POST /v1/marketplace/apps/<id>/install with DELETE method returns 403 if the target app has system=True — federal invariant I-SYSTEM-APPS-NEVER-UNINSTALLABLE. Users cannot remove a system app from their account, period.
Federal invariants
| Invariant | Layer | Pin |
|---|---|---|
I-SYSTEM-APPS-NEVER-UNINSTALLABLE | auth-gw | DELETE on system app → 403 |
I-MARKETPLACE-HIDES-SYSTEM | SQL | Every /v1/marketplace/* SELECT has AND system = FALSE |
I-SYSTEM-FLAG-RESERVED-FOR-IMPERAL | SDK + Dev Portal | Only Imperal authors may publish system=True |
What it does not mean
system=Truedoes not bypass@chat.functionpermissions. Tool-level scopes andaction_type="destructive"confirmations still apply.system=Truedoes not grant web-kernel-level trust. Your extension still runs in the same isolated runner as regular apps; it just happens to be installed by default.system=Truedoes not exempt you from validators. V14-V22, V24, and V31 all still apply.
When to use it
Almost never. The flag exists for the four Imperal-owned extensions that are part of the platform UX (Admin, Billing, Developer, Automations). If you are not the platform vendor, you are not the audience for this flag.
If you have a paid product that benefits from being shown to every user by default, the right answer is marketing, not system=True. Set up Featured carousel placement, write better marketplace copy, and rely on the actions counter to demonstrate value.