How to Access the CloddsBot WebChat UI: Complete Setup and Connection Guide

Launch the CloddsBot gateway and navigate to http://localhost:18789/webchat to access the built-in browser client for real-time messaging.

CloddsBot includes a native WebChat UI that provides immediate browser-based interaction without external messaging platforms. This single-page application connects directly to the bot's gateway via WebSocket, offering a streamlined interface for testing and deployment. This guide explains how to start the gateway, authenticate connections, and send messages using the WebChat interface.

Starting the Gateway Server

The WebChat UI is served by the CloddsBot gateway process. You must start this server before the browser client becomes accessible.

Automated Onboarding

Run the interactive setup wizard to launch the gateway automatically:

npx clodds onboard

The wizard configures your environment and starts the gateway on the configured port. Upon completion, it displays the direct URL to open in your browser (typically http://localhost:18789/webchat), as documented in docs/QUICK_START.md at line 20.

Manual Build and Launch

For development or custom configurations, start the gateway manually:

npm install
cp .env.example .env          # Configure ANTHROPIC_API_KEY and optional WEBCHAT_TOKEN

npm run build
npm start                     # Binds to port defined in gateway.port (default 18789)

The gateway reads its listening port from the configuration key gateway.port, defaulting to 18789 when unspecified. If no external channels (Telegram, Discord, etc.) are configured, the CLI prints a reminder that WebChat remains available: "WebChat at http://localhost:18789/webchat will still work" (see src/index.ts lines 53-58).

Opening the WebChat Interface

Once the gateway is running, access the single-page application at:

http://localhost:18789/webchat

The Express server in src/gateway/server.ts (lines 44-50) serves static assets under the /webchat HTTP path. The page loads a React-based client that immediately establishes a WebSocket connection to the /chat endpoint on the same host and port.

WebSocket Connection and Authentication

The WebChat client communicates via WebSocket to transmit and receive messages in real-time.

Connection Endpoint

The browser connects to:

ws://localhost:18789/chat

All message traffic flows through this endpoint, handled by the createWebChatChannel function in src/channels/webchat/index.ts.

Token-Based Authentication

If you enabled authentication via webchat.authToken in your configuration, the UI supports two authentication methods:

1. Query string parameter: Append the token to the URL:

   http://localhost:18789/webchat?token=your-secret-token

2. WebSocket message: Send an auth payload after connection:

   const ws = new WebSocket('ws://localhost:18789/chat');
   
   ws.onopen = () => {
     ws.send(JSON.stringify({
       type: 'auth',
       token: 'your-secret-token',
       userId: 'my-user'
     }));
   };

The server validates tokens in createWebChatChannel (lines 13-22 in src/channels/webchat/index.ts) before allowing message processing.

Sending Messages Programmatically

Once authenticated, the client transmits JSON payloads to trigger bot responses.

Via WebSocket Client

Send standard message payloads using the WebSocket connection:

function sendMessage(text) {
  ws.send(JSON.stringify({
    type: 'message',
    text: text
  }));
}

sendMessage('What markets are trending?');

The server converts these into internal IncomingMessage objects and routes them through the standard message pipeline.

Via Browser Console

Access the global API exposed by the WebChat UI for debugging:

// In the browser console after page load
window.CloddsWebChat.sendMessage('Analyze current BTC trends');

This method wraps the WebSocket communication in a convenient JavaScript interface.

Legacy Interface Access

For minimal environments or debugging, CloddsBot provides a fallback HTML client at:

http://localhost:18789/webchat/legacy

This inline interface, defined in src/gateway/server.ts (lines 52-58), offers basic WebSocket connectivity without the full React application overhead.

Summary

• Start the gateway using clodds onboard or npm start to bind the server to your configured port (default 18789).
• Access the UI at http://localhost:<port>/webchat, served by Express middleware in src/gateway/server.ts.
• Connect via WebSocket to /chat and optionally authenticate using webchat.authToken via query parameters or the auth message protocol defined in src/channels/webchat/index.ts.
• Send messages as JSON payloads type "message", which the gateway converts to IncomingMessage objects for routing.

Frequently Asked Questions

What is the default port for the CloddsBot WebChat UI?

The gateway defaults to port 18789 unless overridden by the gateway.port configuration value. The onboarding wizard and CLI reminders explicitly reference http://localhost:18789/webchat as the standard access point.

Does WebChat work without configuring Telegram or Discord?

Yes. The WebChat channel operates independently of external messaging integrations. As noted in src/index.ts (lines 53-58), the CLI explicitly confirms that the WebChat interface remains functional even when no other channels are configured.

How do I secure the WebChat interface?

Enable the webchat.authToken configuration option. When set, the server validates this token against either the URL query string (?token=...) or the auth WebSocket message payload within the createWebChatChannel handler. Without a valid token, the connection cannot send or receive messages.

Can I use WebChat for automated testing?

Yes. The repository includes integration tests in tests/integration/webchat-auth.test.ts that demonstrate automated connection, authentication, and message flow. You can replicate this pattern using the WebSocket client example to programmatically interact with the bot without browser automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}