This guide explains how to connect to the OpenHands WebSocket API to receive real-time events and send actions to the agent.

​
Overview

OpenHands uses Socket.IO for WebSocket communication between the client and server. The WebSocket connection allows you to:
  1. Receive real-time events from the agent
  2. Send user actions to the agent
  3. Maintain a persistent connection for ongoing conversations

​
Connecting to the WebSocket

​
Connection Parameters

When connecting to the WebSocket, you need to provide the following query parameters:
  • conversation_id: The ID of the conversation you want to join
  • latest_event_id: The ID of the latest event you’ve received (use -1 for a new connection)
  • providers_set: (Optional) A comma-separated list of provider types

​
Connection Example

Here’s a basic example of connecting to the WebSocket using JavaScript: 
import { io } from "socket.io-client";

const socket = io("http://localhost:3000", {
  transports: ["websocket"],
  query: {
    conversation_id: "your-conversation-id",
    latest_event_id: -1,
    providers_set: "github,gitlab" // Optional
  }
});

socket.on("connect", () => {
  console.log("Connected to OpenHands WebSocket");
});

socket.on("oh_event", (event) => {
  console.log("Received event:", event);
});

socket.on("connect_error", (error) => {
  console.error("Connection error:", error);
});

socket.on("disconnect", (reason) => {
  console.log("Disconnected:", reason);
});

​
Sending Actions to the Agent

To send an action to the agent, use the oh_user_action event: 
// Send a user message to the agent
socket.emit("oh_user_action", {
  type: "message",
  source: "user",
  message: "Hello, can you help me with my project?"
});

​
Receiving Events from the Agent

The server emits events using the oh_event event type. Here are some common event types you might receive:
  • User messages (source: "user", type: "message")
  • Agent messages (source: "agent", type: "message")
  • File edits (action: "edit")
  • File writes (action: "write")
  • Command executions (action: "run")
Example event handler: 
socket.on("oh_event", (event) => {
  if (event.source === "agent" && event.type === "message") {
    console.log("Agent says:", event.message);
  } else if (event.action === "run") {
    console.log("Command executed:", event.args.command);
    console.log("Result:", event.result);
  }
});

​
Using Websocat for Testing

Websocat is a command-line tool for interacting with WebSockets. It’s useful for testing your WebSocket connection without writing a full client application.

​
Installation

# On macOS
brew install websocat

# On Linux
curl -L https://github.com/vi/websocat/releases/download/v1.11.0/websocat.x86_64-unknown-linux-musl > websocat
chmod +x websocat
sudo mv websocat /usr/local/bin/

​
Connecting to the WebSocket

# Connect to the WebSocket and print all received messages
echo "40{}" | \
websocat "ws://localhost:3000/socket.io/?EIO=4&transport=websocket&conversation_id=your-conversation-id&latest_event_id=-1"

​
Sending a Message

# Send a message to the agent
echo '42["oh_user_action",{"type":"message","source":"user","message":"Hello, agent!"}]' | \
websocat "ws://localhost:3000/socket.io/?EIO=4&transport=websocket&conversation_id=your-conversation-id&latest_event_id=-1"

​
Complete Example with Websocat

Here’s a complete example of connecting to the WebSocket, sending a message, and receiving events: 
# Start a persistent connection
websocat -v "ws://localhost:3000/socket.io/?EIO=4&transport=websocket&conversation_id=your-conversation-id&latest_event_id=-1"

# In another terminal, send a message
echo '42["oh_user_action",{"type":"message","source":"user","message":"Can you help me with my project?"}]' | \
websocat "ws://localhost:3000/socket.io/?EIO=4&transport=websocket&conversation_id=your-conversation-id&latest_event_id=-1"

​
Event Structure

Events sent and received through the WebSocket follow a specific structure: 
interface OpenHandsEvent {
  id: string;           // Unique event ID
  source: string;       // "user" or "agent"
  timestamp: string;    // ISO timestamp
  message?: string;     // For message events
  type?: string;        // Event type (e.g., "message")
  action?: string;      // Action type (e.g., "run", "edit", "write")
  args?: any;           // Action arguments
  result?: any;         // Action result
}

​
Best Practices

  1. Handle Reconnection: Implement reconnection logic in your client to handle network interruptions.
  2. Track Event IDs: Store the latest event ID you’ve received and use it when reconnecting to avoid duplicate events.
  3. Error Handling: Implement proper error handling for connection errors and failed actions.
  4. Rate Limiting: Avoid sending too many actions in a short period to prevent overloading the server.

​
Troubleshooting

​
Connection Issues

  • Verify that the OpenHands server is running and accessible
  • Check that you’re providing the correct conversation ID
  • Ensure your WebSocket URL is correctly formatted

​
Authentication Issues

  • Make sure you have the necessary authentication cookies if required
  • Verify that you have permission to access the specified conversation

​
Event Handling Issues

  • Check that you’re correctly parsing the event data
  • Verify that your event handlers are properly registered