Imperal Cloud — the first ICNLI AI Cloud OS
Imperal Cloud is the first ICNLI AI Cloud OS — connect your mail, money, projects, servers and notes under one roof and run them all in plain language.
Your mail is in one app. Your money in another. Your projects, your notes, your calendar, your servers — each behind its own login, its own buttons, its own little wall that says you have to be technical to do this. Dozens of tabs. Dozens of dashboards. One human, pulled in dozens of directions, doing all the connecting by hand.
Imperal Cloud is one roof for all of it — and one language to run it: yours.
You connect the pieces of your life in — mail, money, projects, servers, notes, calendars, anything — and from that moment you stop opening four apps to do one thing. You just say what you want, in your own native language, the way you'd ask a person, and it happens.
"Show me what's overdue, pay the invoice from the design studio, and start the backup before I log off."
One sentence. No new interface to learn, no syntax to memorize, no technical wall — just words, the one interface every human already has.
It works because the intelligence lives inside the system, doing the running-around for you — and held to strict rules the whole time, so it can only ever touch your things the way you allowed. You stay in command; it does the work. This is the first cloud you don't operate — you inhabit it: bring in any context of your life, speak plainly, and let it act.
That inward turn — your life is the context, your words are the interface — is the idea at the very heart of it.
New here? Start with What is Webbee? — plain language, no jargon. Want to see how real this is? The engineering receipts are right below.
The first of its kind
For thirty years, "the cloud" meant servers you rented and dashboards you had to learn. Imperal Cloud is something genuinely new: a cloud with the intelligence living inside it.
The AI runs inside the system — not bolted on top. Every other AI assistant sits outside your tools, asking nicely to use them. Webbee runs inside, so it can actually do the work for you — and it can only ever touch your things the way you allowed.
It grows the way an operating system does. Anyone can teach Webbee a new skill, and you switch on only the ones you want. Your cloud becomes exactly the shape of your life.
It doesn't just wait for you. Webbee can notice when something changes and speak up first — a real assistant, not a prompt box that sits there until you type.
Imperal Cloud is the first ICNLI AI Cloud OS — the first complete implementation of the ICNLI protocol — and we can prove it.
→ For skeptics: Why this is the first ICNLI AI Cloud OS — the six-property test, named-alternative scoring, engineering receipts, falsifiable claim of priority by ICNLI.
→ For builders: What we built that nobody else has — 20 platform-and-agent surfaces with no known precedent.
→ Why Webbee is unique: Cloud-modular + proactive by design — two structural firsts on the ICNLI AI Cloud OS.
Get started in 5 minutes
From zero to a deployed Hello World extension. The fastest possible path.
Federal extension contract
What every extension must satisfy. Manifest schema, validators, runtime invariants.
How it all works
Web-kernel, gateway, workers, SDK — the full architecture in one diagram.
Recipes
Copy-paste examples for the most common patterns.
💰 Build extensions, earn real money
Imperal Marketplace is a real revenue surface. Every user action through your extension generates credit flow — your developer_share accrues in real time, withdrawable to USD via Stripe Connect.
Become a developer
Annual tier subscription unlocks marketplace publish + payouts. Free explorer tier to start.
Tiers & revenue split
70% → 95% developer share across 4 tiers. Higher tier = more per call + bigger app cap.
Pricing your extension
free / per-action / subscription. Set credit cost per function, Imperal handles the wallet.
Payouts to USD
Withdraw earnings via Stripe Connect — verify once, request anytime, paid 2-7 business days.
Pick your starting line
I'm new here
Start with What is Webbee → Quick Start → Your First Extension. About 30 minutes total.
I have an idea
Jump straight to Building Extensions guide. Real walkthrough with typed args, panels, audit.
I'm reading the contract
The complete manifest schema, decorator reference, and the federal validators every extension must pass.
What you can build
Chat extensions
Typed @chat.function handlers. The LLM calls them when users ask for things in natural language.
Panels
React-rendered surfaces inside the Imperal Panel. Sidebars, editors, settings, dashboards.
Skeletons
Live data feeds. Webbee constantly knows the user's mail counts, calendar, project state — without prompting.
Long-running ops
60-90s AI calls and beyond. Three primitives: ctx.http timeout, ctx.background_task, @chat.function(background=True).
Scheduled jobs
@ext.schedule for cron-driven periodic work.
Install in one line
pip install imperal-sdkfrom imperal_sdk import Extension, ChatExtension, ActionResult
from pydantic import BaseModel, Field
class GreetParams(BaseModel):
name: str = Field(description="Person to greet")
ext = Extension(
"hello-world",
version="1.0.0",
display_name="Hello World",
description="Demo extension that greets people by name with a friendly message.",
icon="icon.svg",
actions_explicit=True,
)
chat = ChatExtension(ext, "hello_world", description="Hello World — friendly greetings.")
@chat.function("greet", action_type="read", description="Greet someone by name with a friendly message.")
async def greet(ctx, params: GreetParams) -> ActionResult:
return ActionResult.success(
data={"text": f"Hello, {params.name}! 🐝"},
summary=f"Greeted {params.name}",
)That's a real, working extension. The LLM will call greet(name="Alex") when a user types "say hi to alex".
Where this docs site lives
You're reading docs.imperal.io — the public reference for everyone building on Imperal Cloud. Sister surfaces: panel.imperal.io (end-user UI), panel.imperal.io/developer (publish + marketplace), auth.imperal.io (OAuth, federation).
Built on hard guarantees
Federal-grade
Every action passes through an audit chokepoint. Tenant isolation enforced at the web-kernel layer. Runtime invariants block PRs that weaken them.
Typed by default
@chat.function uses Pydantic for parameters. The LLM gets a JSON schema, the SDK auto-validates, and a feedback loop retries when args come back wrong.
Multi-tenant
One extension serves many tenants simultaneously. The web-kernel passes the right user_id everywhere, fail-closed.
Install / upgrade
pip install --upgrade imperal-sdk| Manifest schema | v3 (federal contract v4.0) |
| Validators | V14-V24, V31 — most ERROR severity; a few (e.g. V20 effects, the V24 data_model recommendation) are WARN |
| Anthropic compatibility | Sonnet 4.6, Haiku 4.5, Opus 4.8 |
| OpenAI compatibility | gpt-4.1, gpt-5 family, o3, o-series |
| GitHub | imperalcloud/imperal-sdk |
For per-release migration notes see the SDK changelog.
All pages on this site
A complete map of everything documented here. Pick anything to jump in.
🚀 Getting Started
What is Webbee?
Plain-language introduction. No jargon.
Quick Start
Build a working extension in 5 minutes.
Installation
Python, the SDK, and editor setup — macOS / Linux / Windows.
Your First Real Extension
A real walkthrough — typed params, panels, audit.
🧠 Core Concepts
Architecture
The full path from chat message to your handler.
Extensions
What an extension actually is — files, lifecycle, types.
@chat.function
The decorator that powers every LLM-callable tool.
Skeletons
Live data feeds — how Webbee always knows your state.
Panels
UI surfaces in the Imperal Panel app.
Web-kernel context (ctx)
Everything every handler receives.
Long-running operations
Ops over 30s — ctx.background_task, ctx.deliver_chat_message (v4.2.12+).
Federal invariants
The 117+ I-* runtime contracts.
🛠️ Guides
Building extensions
Long-form walkthrough — handlers, panels, skeletons together.
Pydantic typed args
LLM-friendly Pydantic schemas.
BYOLLM
Use the user's own LLM provider in your extension.
Confirmations
The confirmation flow for destructive actions.
Chains
Multi-step actions — one message, several tools in sequence.
Audit & security
Action ledger, retention classes, what's recorded.
📐 SDK Reference
SDK overview
Install, hello world, reference index.
Complete API surface
EVERY SDK element on one scrollable page — Cmd-F to find anything.
Manifest reference
Every field of imperal.json explained.
Decorators reference
Every decorator the SDK ships.
Validators reference
V14-V24 + V31 in detail — ERROR and WARN severities.
Federal contract
The complete contract every published extension satisfies.
Pydantic feedback loop
The runtime retry layer + 5 federal invariants.
Changelog
Release notes.
📚 Recipes
Send an email
Federal-clean send_email tool, copy-paste runnable.
Create a note
Classifier owns content generation.
Multistep chain
One user message, two tools in sequence.
BYOLLM extension
Extension that calls an LLM itself via ctx.ai.complete.
Long-running AI calls
60-90s AI generation via ctx.background_task (v4.2.12+).
📖 Reference
Glossary
Every Imperal Cloud / Webbee term you'll see in the docs.
Error codes
What each code means and how to fix it.
FAQ
Frequently asked questions.