📡 Servers - DevDuck Communication Endpoints

📡

Multiple Endpoints

Connect to DevDuck via WebSocket for web apps, TCP for scripts, or Unix sockets for local IPC. All with real-time streaming.

🔌 Available Servers

🌐

WebSocket

ws://localhost:8080

Real-time streaming for web browsers and apps. JSON messages with turn tracking.

🔗

TCP

tcp://localhost:9999

Raw TCP for scripts and CLI tools. Simple text protocol with streaming.

🔌

IPC (Unix Socket)

/tmp/devduck_main.sock

Fast local communication. Best for same-machine agent coordination.

⚙️ Configuration

Variable	Default	Description
`DEVDUCK_ENABLE_WS`	true	Enable WebSocket server
`DEVDUCK_WS_PORT`	8080	WebSocket port
`DEVDUCK_ENABLE_TCP`	false	Enable TCP server
`DEVDUCK_TCP_PORT`	9999	TCP port
`DEVDUCK_ENABLE_IPC`	false	Enable IPC server
`DEVDUCK_IPC_SOCKET`	/tmp/devduck_main.sock	Unix socket path

# Enable all servers
export DEVDUCK_ENABLE_WS=true
export DEVDUCK_ENABLE_TCP=true
export DEVDUCK_ENABLE_IPC=true

devduck

🌐 WebSocket Server

JSON-based protocol with turn tracking, streaming chunks, and tool status updates.

Message Types

Type	Direction	Description
`connected`	Server→Client	Connection established
`turn_start`	Server→Client	New conversation turn started
`chunk`	Server→Client	Streaming text chunk
`tool_start`	Server→Client	Tool invocation started
`tool_end`	Server→Client	Tool completed (success/error)
`turn_end`	Server→Client	Turn completed
`error`	Server→Client	Error occurred

Example Client

const ws = new WebSocket('ws://localhost:8080');

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    
    switch(msg.type) {
        case 'chunk':
            process.stdout.write(msg.data);
            break;
        case 'tool_start':
            console.log(`🛠️ Tool #${msg.tool_number}: ${msg.data}`);
            break;
        case 'turn_end':
            console.log('\\n✅ Complete');
            break;
    }
};

ws.onopen = () => ws.send('Hello DevDuck!');

Tool API

# Start WebSocket server
websocket(action="start_server", port=8080)

# Check status
websocket(action="get_status")

# Stop server
websocket(action="stop_server")

🔗 TCP Server

Simple text protocol for scripts and CLI tools. Responses stream in real-time.

Usage

# Connect with netcat
echo "list all files" | nc localhost 9999

# Or use the TCP client
python -c "
import socket
s = socket.socket()
s.connect(('localhost', 9999))
s.send(b'what time is it?')
while True:
    data = s.recv(4096)
    if not data: break
    print(data.decode(), end='')
"

Tool API

# Start TCP server
tcp(action="start_server", port=9999)

# Send message to TCP server
tcp(action="send", host="localhost", port=9999, message="hello")

# Stop server
tcp(action="stop_server")

🔌 IPC Server (Unix Socket)

Fastest option for local inter-process communication. No network overhead.

Usage

# Connect with socat
echo "status" | socat - UNIX-CONNECT:/tmp/devduck_main.sock

# Python client
python -c "
import socket
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect('/tmp/devduck_main.sock')
s.send(b'what is 2+2?')
print(s.recv(4096).decode())
"

Tool API

# Start IPC server
ipc(action="start_server", socket_path="/tmp/devduck.sock")

# Send message
ipc(action="send", socket_path="/tmp/devduck.sock", message="hello")

# Stop server
ipc(action="stop_server")

🔀 Port Conflict Handling

DevDuck automatically finds available ports if defaults are in use:

# If port 8080 is in use:
🦆 Port 8080 in use, using 8081
🦆 ✓ WebSocket server: localhost:8081

# Same for TCP and IPC sockets