Imperal Cloud โ the AI Cloud OS where the AI runs inside the kernel, not on top
First complete implementation of the ICNLI protocol. Webbee ๐ is its native agent. Write one function; the OS handles auth, audit, isolation, retries, multi-tenant โ the AI cannot side-effect anything except through us.
Imperal Cloud is the AI Cloud OS where the AI runs inside the kernel โ not on top of it. Other platforms ask the AI to behave: tool-use protocols, agent libraries, plugin stores. We built the kernel that contains it. Every action the AI takes passes through a federal contract enforcing authorization, isolation, audit, and anti-hallucination โ before your extension code runs.
The world's first complete implementation of ICNLI โ Infrastructure Contextual Natural Language Interface, the open protocol we authored and published under CC BY-SA 4.0 that maps natural-language intent to context-aware infrastructure actions. Anyone can implement ICNLI; we are the first who shipped it as a deployed multi-tenant cloud OS.
Webbee ๐ is its native agent โ and it's two more firsts in one.
First cloud-modular AI agent. Every other AI agent today is a closed monolith with a bolted-on plugin store owned by one vendor. Webbee is the first AI agent that gains capabilities the same way an OS does โ through federally-contracted extension packages authored by anyone, installable per-user, runtime-dynamic, LLM-provider-agnostic.
First proactive AI agent by design. ChatGPT, Claude, Gemini โ all reactive. They wait for the user. Webbee is the first AI agent where proactive behavior is structural: ambient skeletons keep it aware, schedules let it act on time, webhooks let it react to events, and the platform owns chat-injection so the agent can speak first when something changes. No polling loops; no author plumbing.
You write one function. The OS handles authentication, per-user isolation, RBAC scopes, action-type confirmation gates, audit ledger, retries, timeouts, cancellations, long-running task delivery, multi-tenant safety, anti-hallucination invariants, and chain orchestration across extensions. The same way a Linux dev doesn't write their own network driver โ you don't write your own AI-safety layer.
Welcome to Web 3.0.3 โ three patches past the hype.
โ For skeptics: Why this is the 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 zero precedent.
โ Why Webbee is unique: Cloud-modular + proactive by design โ two distinct firsts neither competitor can claim.
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 token 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 token 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 11 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, tool_name="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-V22, V24, V31 all ERROR severity |
| Anthropic compatibility | Sonnet 4.6, Haiku 4.5, Opus 4.7 |
| 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
Pre-Authorized Action Execution flow.
Chains
Multi-step actions, typed pipe via ctx.prior.
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-V22+V24+V31 in detail.
Federal contract
The complete contract every published extension satisfies.
Pydantic feedback loop
The runtime retry layer + 5 federal invariants.
Changelog
Release notes for the v4.x line.
๐ 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.llm.
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.