Skip to main content

​
Model loading

The Oasis runtime loads models into your device’s memory. If loading stalls:
  • Check available memory. Close other memory-intensive apps (browsers with many tabs, video editors) and try again.
  • Try a smaller model. Switch to a lower tier in Settings > AI Model. Smaller models require less memory and load faster.
  • Refresh the app. On desktop, use Cmd+R (macOS) or Ctrl+R (Windows/Linux). In the browser, do a hard refresh (Cmd+Shift+R).
  • Check WebGPU support. If using the browser, open chrome://gpu and confirm WebGPU is enabled. Some browsers and older GPUs don’t support it.
  • The model may be too large for your hardware. Try a smaller tier.
  • If responses appear empty, the model may have hit the max token limit. Check your app’s maxTokens setting.
  • On Apple Silicon, ensure you’re using the desktop app — it uses the MLX backend, which is significantly faster than browser-based WebGPU.

​
Connecting to spaces

  • Double-check the code. Room codes are case-sensitive.
  • Confirm the space is still active. Spaces are removed after all participants leave and no relay is active. Ask the host to confirm the space is running.
  • Check your network. If you’re behind a VPN or strict corporate firewall, WebRTC connections may be blocked. Try disabling the VPN temporarily or switching to a different network.
Connection establishment can take up to 15 seconds. If participants still don’t appear:
  • Firewall rules. WebRTC uses UDP on ephemeral ports. Corporate firewalls that block outbound UDP will prevent peer connections. TURN relay servers handle most NAT traversal, but some networks block relay traffic too.
  • Different networks. If both peers are on different networks, the connection routes through TURN relay servers. This usually works but adds latency.
  • Same network. If both peers are on the same LAN, local discovery should connect them directly. Ensure both devices are on the same Wi-Fi or subnet.

​
Voice chat

  • Grant permission. When prompted, allow microphone access. If you previously denied it, reset permissions in your browser or OS settings.
  • Check device selection. Ensure the correct microphone is selected in your system sound settings.
  • Desktop app. On macOS, go to System Settings > Privacy & Security > Microphone and confirm webAI has access.
  • Your microphone may be muted in webAI. Check the mic icon in the voice panel.
  • Try leaving and rejoining voice chat.
  • If the issue persists, refresh the app and rejoin the space.

​
Apps

  • Apps are stored in your browser’s localStorage. If you cleared browser data, the app is gone and needs to be re-uploaded.
  • Confirm the upload completed without errors in the browser console (Cmd+Option+J on macOS or F12 on Windows).
  • The file must be a single, self-contained HTML file. If your app depends on external resources, bundle them first with a tool like Vite and vite-plugin-singlefile.
  • Shell APIs (OasisHost, CollaborationManager) are only available when running inside the webAI shell. If you see null or undefined, your app may be running in a standalone browser tab.
  • Ensure a model is loaded before making inference requests. Use probeOasisState() from the webAI SDK to check — the state must be 'ready'.
  • If using personas, the user must grant permission the first time. The permission prompt appears automatically.
Your app needs to listen for canvas:theme messages from the shell. Add this to your app’s JavaScript:
window.addEventListener('message', (e) => {
  if (e.data?.type === 'canvas:theme') {
    document.documentElement.setAttribute('data-theme', e.data.theme);
  }
});

​
Storage

webAI stores data in localStorage and IndexedDB. If you hit quota limits:
  • Clear old data. Go to Settings > Data & Storage and use the cleanup options to remove old files and cached data.
  • Factory reset. As a last resort, use Settings > System > Factory Reset to clear all local data. This removes your identity, contacts, apps, and chat history permanently.
  • Browser limits. Most browsers cap localStorage at 5–10 MB per origin. The desktop app has higher limits.
Your identity (ODID) and contacts are stored locally. If browser data is cleared, they cannot be recovered. To prevent this:
  • Use the desktop app, which stores data outside the browser’s cache.
  • Avoid clearing site data for the webAI origin in your browser settings.

​
Contacts

  • Peer codes are valid for 30 seconds. Generate a new one if the countdown has elapsed.
  • Both devices must be able to reach the signaling server. Check your network connection.
  • Ensure you’re copying the full 6-digit code without extra spaces.

​
Still need help?

If none of the above resolves your issue, try these steps:
  1. Check diagnostics. If developer mode is enabled, open the diagnostics panel for a system health snapshot.
  2. Refresh. A full app refresh resolves most transient issues.
  3. Update. Make sure you’re running the latest version of webAI.