fix: change SDK default WebSocket URL to production endpoint

[sebuh-infsol]

Summary

The SDK AppSession was defaulting to ws://localhost:8002/app-ws (local dev server) instead of the production endpoint. This caused third-party apps to fail connecting with "Connection timeout after 5000ms" errors when deployed outside the local dev environment.

Changes

Changed default from ws://localhost:8002/app-ws to wss://api.mentra.glass/app-ws in:

• cloud/packages/sdk/src/app/session/index.ts — SDK source code
• cloud/docs/api-reference/websocket/app-connection.mdx — API reference docs
• docs/app-devs/reference/app-session.mdx — AppSession reference docs

Impact

• Third-party apps will now connect to the production MentraOS Cloud by default
• Local development still works — devs can override with mentraOSWebsocketUrl: 'ws://localhost:8002/app-ws' in their app config
• Fixes the common "couldn't connect" error when deploying apps to production

Testing

Verified by deploying the camera app to SCARRED — sessions now connect successfully instead of timing out.

---

Note

Medium Risk
Changing the SDK default affects all apps that omit mentraOSWebsocketUrl, so local workflows must override explicitly; connection behavior is core to app runtime.

Overview
AppSession now defaults mentraOSWebsocketUrl to wss://api.mentra.glass/app-ws instead of ws://localhost:8002/app-ws, so deployed third-party apps connect to production MentraOS Cloud without setting the URL explicitly. Local dev can still override with the localhost endpoint.

Docs are aligned: the app WebSocket API reference renames the local tab to Local Development, and the AppSessionConfig reference documents the new production default.

^{Reviewed by Cursor Bugbot for commit 93fc6b0. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Set the SDK AppSession default WebSocket to wss://api.mentra.glass/app-ws to prevent connection timeouts in deployed apps. Local dev can still override with mentraOSWebsocketUrl: 'ws://localhost:8002/app-ws'.

• Bug Fixes
  • Updated default in cloud/packages/sdk/src/app/session/index.ts.
  • Synced docs in cloud/docs/api-reference/websocket/app-connection.mdx and docs/app-devs/reference/app-session.mdx.

^{Written for commit 93fc6b0. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/app-devs/reference/app-session.mdx">

<violation number="1" location="docs/app-devs/reference/app-session.mdx:288">
P2: JSDoc comment for `mentraOSWebsocketUrl` is missing closing quote and `*/`, breaking the TypeScript interface example syntax</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: JSDoc comment for mentraOSWebsocketUrl is missing closing quote and */, breaking the TypeScript interface example syntax

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/app-devs/reference/app-session.mdx, line 288:

<comment>JSDoc comment for `mentraOSWebsocketUrl` is missing closing quote and `*/`, breaking the TypeScript interface example syntax</comment>

<file context>
@@ -285,7 +285,7 @@ interface AppSessionConfig {
   apiKey: string;
 
-  /** The WebSocket URL provided by MentraOS Cloud. Defaults to 'ws://localhost:8002/app-ws'. */
+  /** The WebSocket URL provided by MentraOS Cloud. Defaults to 'wss://api.mentra.glass/app-ws.
   mentraOSWebsocketUrl?: string;
 
</file context>

Suggested change

	/** The WebSocket URL provided by MentraOS Cloud. Defaults to 'wss://api.mentra.glass/app-ws.
	+ /** The WebSocket URL provided by MentraOS Cloud. Defaults to 'wss://api.mentra.glass/app-ws'. */