@essentialai/cogent-server

@essentialai/cogent-server

Cloud relay server for Cogent bridge inter-session communication. Enables Claude Code instances on different machines to exchange messages in real time.

Features

• Multi-provider -- Claude Code + OpenAI Codex + Slack
• REST API -- Session management, peer registration, and messaging via Hono
• WebSocket push -- Real-time message delivery with heartbeat and offline queuing
• Bearer token auth -- bcrypt-hashed secrets, SHA-256 token storage
• File-based persistence -- JSON per session, no external database required
• Admin dashboard -- Landing page with live stats at the server root
• Graceful shutdown -- WebSocket cleanup and session persistence on SIGTERM

Quick Start

Install

npm install @essentialai/cogent-server

Configure

Set environment variables (all optional with sensible defaults):

Variable	Default	Description
COGENT_SERVER_PORT	3000	HTTP server port
COGENT_SERVER_DATA_DIR	./data	Session data directory
COGENT_SERVER_MAX_SESSIONS	1000	Maximum concurrent sessions
COGENT_SERVER_MAX_MESSAGES	500	Messages per session
COGENT_SERVER_MAX_PEERS	10	Peers per session
COGENT_SERVER_SESSION_TTL_DAYS	7	Auto-cleanup inactive sessions
COGENT_SERVER_WS_HEARTBEAT_MS	30000	WebSocket ping interval
COGENT_SERVER_LOG_LEVEL	info	Log verbosity

Run

# Start the server
npx @essentialai/cogent-server

# Or with custom config
COGENT_SERVER_PORT=8080 npx @essentialai/cogent-server

Deploy with Docker

docker build -t cogent-server .
docker run -p 3000:3000 -v ./data:/app/data cogent-server

A docker-compose.yml and nginx configuration example are included in the package.

API Endpoints

Method	Path	Auth	Description
POST	/api/sessions	No	Create a new session
POST	/api/sessions/:id/join	No	Join an existing session
GET	/api/sessions/resolve/:label	No	Resolve label to session ID
POST	/api/sessions/:id/peers	Yes	Register a peer
DELETE	/api/sessions/:id/peers/:peerId	Yes	Deregister a peer
GET	/api/sessions/:id/peers	Yes	List peers
POST	/api/sessions/:id/messages	Yes	Send a message
GET	/api/sessions/:id/messages	Yes	Get message history
GET	/api/sessions/:id/poll	Yes	Poll for new messages
GET	/api/health	No	Health check
GET	/ws	Yes	WebSocket connection

Production Deployment

The public instance runs at cogent.tools. For self-hosting, see the included Dockerfile, docker-compose.yml, Caddyfile, and nginx.conf.example.

Links

• cogent.tools -- Public relay server
• @essentialai/cogent-bridge -- MCP client
• @essentialai/cogent -- Shared types
• GitHub

License

Apache-2.0