Use Case: Web Dashboard with AI Assistant

octomind server --host 127.0.0.1 --port 8080

octomind server assistant -p 8080

octomind server assistant --host 0.0.0.0 --port 8080

class OctomindClient {
  private ws: WebSocket;
  private sessionId: string;
  private handlers: {
    onMessage: (content: string) => void;
    onToolUse: (tool: string, params: any) => void;
    onCost: (cost: number) => void;
    onError: (error: string) => void;
  };

  constructor(url: string, sessionId: string, handlers: typeof this.handlers) {
    this.sessionId = sessionId;
    this.handlers = handlers;
    this.ws = new WebSocket(url);

    this.ws.onopen = () => {
      // Initialize session
      this.ws.send(JSON.stringify({
        type: 'session',
        session_id: this.sessionId
      }));
    };

    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      switch (msg.type) {
        case 'status':
          // The server replies to `session` with a status carrying the
          // ACTUAL session_id ("Session created: <id>" / "Session resumed: <id>").
          // When you omit session_id the server auto-names the session, so
          // always capture the returned id and use it for subsequent messages.
          if (msg.session_id) this.sessionId = msg.session_id;
          break;
        case 'assistant':
          this.handlers.onMessage(msg.content);
          break;
        case 'tool_use':
          this.handlers.onToolUse(msg.tool, msg.params);
          break;
        case 'cost':
          // `cost` is emitted once after each completed AI turn — the
          // canonical end-of-turn signal.
          this.handlers.onCost(msg.session_cost);
          break;
        case 'ack':
          // Optional immediate receipt signal. Use request_id if you need
          // per-input correlation.
          break;
        case 'error':
          this.handlers.onError(msg.message);
          break;
      }
    };
  }

  send(message: string) {
    this.ws.send(JSON.stringify({
      type: 'message',
      session_id: this.sessionId,
      content: message
    }));
  }

  command(cmd: string) {
    // `command` is the bare command name WITHOUT the leading slash —
    // the server prepends '/'. Sending '/info' would become '//info'.
    // Unknown commands come back as an `error` payload.
    this.ws.send(JSON.stringify({
      type: 'command',
      session_id: this.sessionId,
      command: cmd
    }));
  }
}

// Usage
const ai = new OctomindClient('ws://localhost:8080', 'dev-session', {
  onMessage: (content) => appendToChat(content),
  onToolUse: (tool, params) => showToolActivity(tool),
  onCost: (cost) => updateCostDisplay(cost),
  onError: (error) => showError(error),
});

ai.send('Explain how authentication works in this project');
ai.command('info');  // Get session stats (note: bare name, no leading slash)

# /etc/nginx/sites-available/octomind
server {
    listen 443 ssl;
    server_name ai.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/ai.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.yourcompany.com/privkey.pem;

    # WebSocket proxy
    location /ws {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # Static frontend
    location / {
        root /var/www/dashboard;
        try_files $uri /index.html;
    }
}

import asyncio
import json
import websockets

async def ask_octomind(question: str) -> str:
    async with websockets.connect('ws://127.0.0.1:8080') as ws:
        await ws.send(json.dumps({
            'type': 'session',
            'session_id': 'api-session'
        }))

        await ws.send(json.dumps({
            'type': 'message',
            'session_id': 'api-session',
            'content': question
        }))

        response_parts = []
        async for message in ws:
            msg = json.loads(message)
            if msg['type'] == 'assistant':
                response_parts.append(msg['content'])
            elif msg['type'] == 'cost':
                # `cost` is emitted once after each completed AI turn — the
                # canonical end-of-turn marker. `status` text is free-form and
                # never reliably signals completion, so don't parse it for that.
                break

        return ''.join(response_parts)

# Usage
answer = asyncio.run(ask_octomind("What does the login function do?"))

const alice = new OctomindClient(url, 'alice-session', handlers);
const bob = new OctomindClient(url, 'bob-session', handlers);

alice.send('Review the auth module');
bob.send('Help me write tests for the API');
// Both sessions run independently