Accessing shell APIs

The universal pattern for safely accessing webAI platform APIs from your app.

The webAI shell injects a set of JavaScript globals into your app’s iframe window. These globals are your gateway to AI inference, collaboration, identity, encryption, and navigation. This page covers how to access them safely and reliably.

Prefer the webAI SDK for new apps. The SDK wraps these globals with typed helpers, a React hook, streaming utilities, and chat memory management. See the webAI SDK reference.

The access pattern

Every shell API follows the same pattern: check window first, then fall back to window.parent. This handles both direct injection and cases where your app is nested in an iframe hierarchy.

const getShellAPI = (name) =>
  window[name] ?? window.parent?.[name] ?? null;

Use this helper to access any platform API:

const OasisHost            = getShellAPI('OasisHost');
const ApogeeShell          = getShellAPI('ApogeeShell');
const CollaborationManager = getShellAPI('CollaborationManager');
const UserIdentityManager  = getShellAPI('UserIdentityManager');
const E2ECrypto            = getShellAPI('E2ECrypto');

All of these values will be null when your app runs outside the webAI shell (e.g., during local development with npm run dev). Always check for null before calling any methods.

The integration module

Rather than scattering window.OasisHost ?? window.parent?.OasisHost throughout your codebase, create a single webai.js module as your integration layer:

// src/webai.js
export const getShellAPI = (name) =>
  window[name] ?? window.parent?.[name] ?? null;

export const getOasisHost            = () => getShellAPI('OasisHost');
export const getApogeeShell          = () => getShellAPI('ApogeeShell');
export const getCollaborationManager = () => getShellAPI('CollaborationManager');
export const getUserIdentityManager  = () => getShellAPI('UserIdentityManager');
export const getE2ECrypto            = () => getShellAPI('E2ECrypto');

Then import from this module wherever you need platform access:

import { getOasisHost, getCollaborationManager } from './webai';

This keeps all shell-specific code in one place and makes it easy to add mocks for local development.

Available APIs

OasisHost — On-device AI inference

Run AI models locally. Acquire the runtime, stream completions token-by-token, and check model status — all without network requests.

Method	Description
acquire(options)	Lock the AI runtime for exclusive use. Returns a release function
request(prompt, options)	Send a prompt and receive a streamed completion
release()	Release the runtime lock
getStatus()	Get current model and runtime state

Full OasisHost reference →

CollaborationManager — P2P spaces and state sync

Host or join peer-to-peer collaboration spaces. Broadcast state changes, receive updates from other users, and let the platform handle networking and conflict resolution.

Method	Description
hostRoom(options)	Create a new collaboration space
joinRoom(code, password)	Join an existing space by code
disconnect()	Leave the current space and disconnect
getRoomSettings()	Get current space settings (name, public/private, etc.)
getUsers()	Get the map of connected users
sendChatMessage(text)	Send a message to the space chat
requestLock(fieldKey)	Lock a field for editing
releaseLock(fieldKey)	Release an edit lock

Full CollaborationManager reference →

UserIdentityManager — Identity and authentication

Access the current user’s device identity (ODID), display name, and authentication headers for peer-to-peer communication.

Method	Description
getOrCreateIdentity()	Returns the user’s ODID and display name
getAuthHeaders()	Returns authentication headers for P2P requests

Full identity reference →

ApogeeShell — Navigation and view routing

Control which view is displayed in the webAI shell. Switch to built-in views like the whiteboard, browser, or collaborative editor.

Method	Description
setView(viewId)	Navigate to a specific shell view

Full navigation reference →

E2ECrypto — End-to-end encryption

Encrypt and decrypt data for secure peer-to-peer communication. Used internally by the collaboration system and available for your own encrypted data flows.

Full encryption reference →

Handling the dev environment

When running locally (outside the webAI shell), all APIs return null. Here’s a clean way to handle this across frameworks:

React

import { getOasisHost } from './webai';

function App() {
  const isInShell = !!getOasisHost();

  return (
    <div>
      {!isInShell && (
        <div className="dev-banner">
          Running outside webAI — platform features unavailable
        </div>
      )}
      {/* Your app content */}
    </div>
  );
}

Vue

<template>
  <div>
    <div v-if="!isInShell" class="dev-banner">
      Running outside webAI — platform features unavailable
    </div>
    <!-- Your app content -->
  </div>
</template>

<script setup>
import { getOasisHost } from './webai';
const isInShell = !!getOasisHost();
</script>

Next steps

OasisHost API

Add on-device AI inference to your app.

CollaborationManager API

Build real-time multiplayer experiences.