Developer Documentation

Client Connection Guide

Learn how to configure your frontend and backend applications to broadcast and listen for sub-millisecond events with OsciWave.

1. Quickstart & API Credentials

To connect to OsciWave, obtain your credentials from your account dashboard:

Credential Field Example Value
App ID ow_app_849204
App Key ow_key_7392019482736451
App Secret sk_sec_9938201928475612
WebSocket Host ws.osciwave.com:443

Add these environment variables to your application's .env file:

REVERB_APP_ID=ow_app_849204
REVERB_APP_KEY=ow_key_7392019482736451
REVERB_APP_SECRET=sk_sec_9938201928475612
REVERB_HOST=ws.osciwave.com
REVERB_PORT=443
REVERB_SERVER_PORT=8081
REVERB_SCHEME="https"
AI agents

2. AI Agent MCP Setup

Generate a workspace-scoped agent API key from Settings → API keys, then connect your client to the Streamable HTTP endpoint below.

https://osciwave.com/mcp
Keep the bearer token in a local environment variable or secret prompt. Do not commit it to a repository. The token is shown once, stored as a hash by OsciWave, scoped to the current workspace, and can be revoked at any time.

Cursor

Save as .cursor/mcp.json for the project or ~/.cursor/mcp.json globally.

{
  "mcpServers": {
    "osciwave": {
      "url": "https://osciwave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:OSCIWAVE_MCP_TOKEN}"
      }
    }
  }
}

Claude Code

Save as .mcp.json in the project root; Claude expands the token from your environment.

{
  "mcpServers": {
    "osciwave": {
      "type": "http",
      "url": "https://osciwave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OSCIWAVE_MCP_TOKEN}"
      }
    }
  }
}

VS Code with GitHub Copilot

Save as .vscode/mcp.json. VS Code prompts for the token and keeps it out of the file.

{
  "servers": {
    "osciwave": {
      "type": "http",
      "url": "https://osciwave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:osciwaveToken}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "osciwaveToken",
      "description": "OsciWave agent API key",
      "password": true
    }
  ]
}

Gemini CLI

Add this to .gemini/settings.json for the project or ~/.gemini/settings.json globally.

{
  "mcpServers": {
    "osciwave": {
      "httpUrl": "https://osciwave.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OSCIWAVE_MCP_TOKEN}"
      }
    }
  }
}

Codex CLI, IDE extension, and ChatGPT desktop

Codex uses TOML rather than JSON. Add this to ~/.codex/config.toml or a trusted project’s .codex/config.toml; the same configuration is shared with the Codex IDE extension and ChatGPT desktop app.

[mcp_servers.osciwave]
url = "https://osciwave.com/mcp"
bearer_token_env_var = "OSCIWAVE_MCP_TOKEN"

What the agent can do

  1. Call download_skill to load the OsciWave workflow.
  2. Call create_project with a GitHub, GitLab, file, URL, or other stable source identity.
  3. Call install_reverb for dependency, environment, and verification steps.
  4. Call connect_project to retrieve the authenticated project configuration.

3. Connecting via Laravel Echo

OsciWave is fully compatible with `laravel-echo` and `pusher-js`. Install the dependencies in your frontend project:

npm install --save laravel-echo pusher-js

Configure `resources/js/bootstrap.js` with your OsciWave socket parameters:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_OSCIWAVE_APP_KEY,
    wsHost: import.meta.env.VITE_OSCIWAVE_HOST ?? 'ws.osciwave.com',
    wssPort: import.meta.env.VITE_OSCIWAVE_PORT ?? 443,
    forceTLS: true,
    enabledTransports: ['ws', 'wss'],
});

// Listening for real-time events
window.Echo.channel('orders')
    .listen('OrderProcessed', (e) => {
        console.log('Order event received:', e);
    });

4. Connecting via Standard Pusher JS

You can also connect directly using the vanilla `pusher-js` client library without Laravel Echo:

import Pusher from 'pusher-js';

const pusher = new Pusher('ow_key_7392019482736451', {
    wsHost: 'ws.osciwave.com',
    wssPort: 443,
    forceTLS: true,
    disableStats: true,
    enabledTransports: ['ws', 'wss']
});

const channel = pusher.subscribe('osciwave-public');
channel.bind('ping', function(data) {
    alert(JSON.stringify(data));
});

5. REST Broadcast API Endpoint

To publish events from any backend language (PHP, Node.js, Python, Go, Ruby), send an HTTP POST request to the REST broadcast endpoint:

POST /api/apps/{app_id}/events

Example `curl` payload request:

curl -X POST "https://ws.osciwave.com/api/apps/ow_app_849204/events" \
  -H "Content-Type: application/json" \
  -H "X-OsciWave-Key: ow_key_7392019482736451" \
  -d '{
    "channel": "orders",
    "name": "OrderProcessed",
    "data": {
      "order_id": 1042,
      "status": "completed",
      "amount": 99.00
    }
  }'

6. Private & Presence Channel Authorization

Private channels require an authorized subscription payload authenticated by an HMAC signature generated by your backend application.

window.Echo.private(`user.${userId}`)
    .listen('NotificationSent', (e) => {
        console.log(e.notification);
    });