System Apps
System apps — first-party Imperal extensions that auto-install for every user, stay hidden from the marketplace, and can never be uninstalled by anyone.
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 listings, featured carousels, category browses, and developer profiles | 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 — the platform refuses the request | Allowed via marketplace card |
The auto-install happens as part of creating the user: the system app is installed in the same operation that creates the account. If that install cannot be completed, the account is not created — 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": "5.4.2",
"app_id": "billing",
...
"system": true,
...
}You never hand-write sdk_version — the build auto-fills it from the installed SDK (here, 5.4.2). The system flag itself was introduced back in Federal v4.2.0, but that history is independent of the SDK version your manifest carries today. The platform requires a current SDK (>= 5.0.0); a manifest carrying an older sdk_version is rejected at load.
What stops abuse
Three layers — defence in depth:
SDK validator V31 (local)
imperal validate runs locally before you publish. V31 is a local pre-check that fires only when the operator supplies both an IMPERAL_AUTHOR_ID and a non-empty IMPERAL_FIRSTPARTY_AUTHOR_IDS allowlist — the SDK ships no embedded list of first-party authors. When both are present and your author id is not in the allowlist, V31 fails with a clear error. If either is unset, V31 does not fire locally and the authoritative gate is the Dev Portal author check below.
✗ V31: Extension(system=True) is reserved for first-party platform extensions.
Author 'imp_u_dimas-...' is not in the first-party 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.
Platform runtime check
At runtime, the platform refuses any request to uninstall a system app. Users cannot remove a system app from their account, period.
Guaranteed behavior
The platform enforces these guarantees for every system app:
- System apps can never be uninstalled. Any attempt to remove one from a user's account is refused.
- System apps are hidden from the marketplace. They never appear in marketplace listings, featured carousels, category browses, or developer profiles.
- The
system=Trueflag is reserved for first-party platform extensions. Only Imperal authors may publish an extension with it set.
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.
See also
Action types
read / write / destructive action types — how Imperal Cloud gates side-effects, audit, and confirmations for every chat function declared in your extension.
Secrets
@ext.secret — store credentials safely: per-user keys and OAuth tokens (scope=user) or shared developer-owned secrets (scope=app), encrypted and never exposed.