@essentialai/cogent-server

Cogent relay server with session management and bearer auth

npm

Version: 3.2.1

Version published: 4 months ago

Maintainers: 1

Created: 6 months ago

Source

@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

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.