A step-by-step guide to building, testing, and deploying your own apps inside webAI — from a single HTML file to a fully collaborative, AI-powered tool.
If you can build a web page, you can build a webAI app. Apps are single HTML files that run inside the platform and get access to on-device AI, real-time collaboration, user identity, and more — with zero server infrastructure.This guide walks you through the entire process, starting with the simplest possible app and progressively adding platform features.
You don’t need any special tooling. For the quick-start path, all you need is a text editor. For framework-based apps (React, Vue, Svelte, etc.) you’ll want Node.js installed and a bundler that can produce a single self-contained HTML file.Here’s a quick look at the two paths:
Path
Best for
Build step?
Vanilla HTML
Prototypes, simple tools, learning the platform
No
Framework (React / Vue / etc.)
Production apps, complex UIs, team projects
Yes — bundle to a single HTML file
Start with vanilla HTML to learn the concepts, then move to a framework when your app outgrows a single hand-written file.
A webAI app is just an HTML file that declares which platform facades it needs through a shell manifest, and then reads from window.apogeeSDK to call them. Here’s a complete, working example that demonstrates AI inference, identity, and theme integration — all in a single file:
Save this as index.html and upload it to webAI — you’ll have a working AI chat app with theme support and a personalized greeting. The sections below break down each piece of the pattern.
The webAI shell injects a single bridge object — window.apogeeSDK — into your app. It exposes platform capabilities as domain-specific facades (sdk.intelligence, sdk.identity, sdk.room, sdk.messaging, and so on).
When your app runs outside the webAI shell (e.g., during local development with npm run dev, or if you double-click the HTML file), sdk is null. Always guard before calling.
Only the facades you list under requires.managers are injected. After loading, check sdk.supportedFacades to see what’s actually available — a facade may be omitted if the current shell doesn’t ship it (for example, a browser-only environment may expose fewer facades than the desktop app).
Now that you know how to access APIs, let’s put them to use. Each section below is independent — add only what your app needs, and declare the matching facade in your manifest.
The intelligence facade lets your app run AI inference directly on the user’s device (or route to a registered cloud backend). Use chatCompletion for a simple request/response pattern:
async function askAI(prompt) { const sdk = window.apogeeSDK || null; if (!sdk?.intelligence) { console.warn("AI not available outside webAI."); return null; } const response = await sdk.intelligence.chatCompletion({ model: "auto", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: prompt } ], max_tokens: 2048, temperature: 0.7 }); return response.content;}
For token-by-token streaming UIs, use chatCompletionStream instead:
async function askAIStreaming(prompt, onDelta) { const sdk = window.apogeeSDK || null; if (!sdk?.intelligence) return; const stream = sdk.intelligence.chatCompletionStream({ model: "auto", messages: [{ role: "user", content: prompt }], max_tokens: 2048 }); for await (const chunk of stream) { if (chunk.delta) onDelta(chunk.delta); if (chunk.finish_reason) break; }}
Key points:
model: "auto" lets the runtime pick the best available backend for the device.
chatCompletion returns the full response after generation completes.
chatCompletionStream is an async iterator — each chunk carries a delta string and an optional finish_reason.
Real-time collaboration is split across four facades — room hosts and joins spaces, messaging handles chat, canvas syncs shared app state, and files shares files inside a space.
const sdk = window.apogeeSDK || null;async function startRoom() { if (!sdk?.room) return; const roomCode = await sdk.room.host({ userName: "Host" }); console.log("Space created! Code:", roomCode);}async function enterRoom(code) { if (!sdk?.room) return; return sdk.room.join({ roomCode: code, userName: "Guest" });}
The collaboration flow:
One user hosts a space with sdk.room.host() — this returns a room code
Others join using that code with sdk.room.join({ roomCode })
Participants exchange state through the platform (chat via messaging, shared app state via canvas)
The platform broadcasts changes, persists state, and resolves conflicts via
Collaboration APIs reference
Covers hosting, joining, canvas state, messaging, file sharing, and best practices.
For anything beyond a simple prototype, a framework with a bundler gives you a better development experience. The only hard requirement is that your build outputs a single self-contained HTML file.Vite with vite-plugin-singlefile is one common path; any bundler that can inline JS, CSS, and assets into one HTML file will work.
Your app opens in a normal browser tab. window.apogeeSDK will be null — this is expected. Design your UI with graceful fallbacks so you can iterate without the full shell running.
Show a subtle banner in dev mode like “Running outside webAI — AI and collaboration unavailable.” This makes it obvious which features need the shell while you focus on building your UI.
Deep dive: App lifecycle
Covers the full development workflow, project structure, bundler config, and uploading.
window.apogeeSDK is null outside of webAI. Wrap every access in a check so your app works during local development and doesn’t crash when a facade isn’t available. Optional chaining (sdk?.intelligence?.chatCompletion?.(...)) is a concise way to do this.
Declare every facade you need in the manifest
Only facades listed under requires.managers are injected. If sdk.room is missing at runtime, check your manifest first. Inspect sdk.supportedFacades to see what the shell actually provided.
Keep your bundle small
Apps under 1MB load quickly. If your build exceeds 5MB, consider optimizing images, removing unused dependencies, or lazy-loading heavy components.
Handle stream cancellation
When using chatCompletionStream, let users cancel long generations. Break out of the for await loop as soon as the user asks to stop, and ignore any remaining chunks. This keeps the UI responsive and avoids wasted compute.
Unsubscribe from facade subscribers
Every facade with subscribe(handler) returns an unsubscribe function. Call it on teardown (useEffect cleanup, onUnmounted, etc.) to avoid memory leaks.
Build your UI and core logic so it works in a normal browser tab. Add platform features on top with graceful fallbacks. This makes development much faster.
