@agentxjs/server

WebSocket server for AgentX. Exposes a JSON-RPC 2.0 API for managing containers, images, agents, and messages. Stream events from running agents are broadcast to subscribed clients.

Overview

@agentxjs/server creates a WebSocket server that accepts client connections, handles JSON-RPC requests via a CommandHandler, and broadcasts LLM stream events as JSON-RPC notifications. It supports two startup modes: standalone (own port) and attached (existing HTTP server).

Quick Start

$3

``typescript
import { createServer } from "@agentxjs/server";
import { nodePlatform } from "@agentxjs/node-platform";
import { createMonoDriver } from "@agentxjs/mono-driver";
import type { CreateDriver } from "@agentxjs/core/driver";

const apiKey = process.env.ANTHROPIC_API_KEY!;

const wrappedCreateDriver: CreateDriver = (config) => {
return createMonoDriver({
...config,
apiKey,
options: { provider: "anthropic" },
});
};

const server = await createServer({
platform: nodePlatform({ dataPath: "./data" }),
createDriver: wrappedCreateDriver,
port: 5200,
});

await server.listen();
// Server listening on ws://0.0.0.0:5200
`

$3

Attach to an existing HTTP server instead of opening a new port:

`typescript
import { createServer as createHttpServer } from "http";
import { createServer } from "@agentxjs/server";
import { nodePlatform } from "@agentxjs/node-platform";

const httpServer = createHttpServer();

const server = await createServer({
platform: nodePlatform({ dataPath: "./data" }),
createDriver: wrappedCreateDriver,
server: httpServer, // attach here
wsPath: "/ws", // WebSocket upgrade path (default: "/ws")
});

// The HTTP server handles listen()
httpServer.listen(3000);
`

$3

`bash
ANTHROPIC_API_KEY=sk-ant-xxx bun run packages/server/bin/server.ts
`

API Reference

$3

Creates and returns an AgentX server instance.

$3

`typescript
interface AgentXServer {
listen(port?: number, host?: string): Promise; // standalone only
close(): Promise;
dispose(): Promise; // full cleanup
}
`

$3

Maps JSON-RPC methods to runtime operations. Exported for advanced use (e.g., custom transports).

`typescript
import { CommandHandler } from "@agentxjs/server";
`

Configuration

$3

`typescript
interface ServerConfig {
platform: AgentXPlatform | DeferredPlatformConfig;
createDriver: CreateDriver;
port?: number; // default: 5200
host?: string; // default: "0.0.0.0"
server?: MinimalHTTPServer; // attach to existing server
wsPath?: string; // default: "/ws" (attached mode)
debug?: boolean;
}
`

| Field | Type | Default | Description |
| -------------- | ------------------------------------------ | ----------- | ------------------------------------------------ |
| platform | AgentXPlatform \| DeferredPlatformConfig | -- | Platform with repositories and event bus |
| createDriver | CreateDriver | -- | Factory function that creates a Driver per agent |
| port | number | 5200 | Standalone listen port |
| host | string | "0.0.0.0" | Standalone bind host |
| server | MinimalHTTPServer | -- | Existing HTTP server to attach to |
| wsPath | string | "/ws" | WebSocket path in attached mode |
| debug | boolean | false | Enable debug logging |

$3

WebSocket connections are automatically monitored with a ping/pong heartbeat (30-second interval). If a client fails to respond, the connection is terminated. This is always enabled and requires no configuration.

`typescript
// Heartbeat is automatic — no config needed
// Server sends ping every 30s, client must respond with pong
// Unresponsive clients are disconnected automatically
`

$3

| Variable | Required | Default | Description |
| -------------------- | -------- | ------------------ | ----------------------------------- |
| ANTHROPIC_API_KEY | Yes | -- | Claude API key |
| ANTHROPIC_BASE_URL | No | -- | Custom API endpoint |
| PORT | No | 5200 | Server port |
| HOST | No | 0.0.0.0 | Server host |
| DATA_PATH | No | ./data | Data storage directory |
| LOG_DIR | No | /logs | Log file directory |
| LOG_LEVEL | No | info | debug / info / warn / error` |