cortex serve
Start the built-in HTTP server with REST API endpoints and WebSocket support for real-time streaming chat. Also serves the CortexPrism web UI dashboard.
Usage
cortex serve # http://127.0.0.1:3000 (foreground)
cortex serve --port 8080 --host 0.0.0.0
cortex serve -d # Run in the background (daemon mode)
cortex serve -d -r # Restart background server on the same port
cortex serve -s # Stop background server
Options
| Option | Description |
|---|---|
--port, -p | HTTP server port (default: 3000) |
--host, -H | Bind address (default: 127.0.0.1) |
-d | Run server in background (daemon mode) |
-r | Restart an existing background server (use with -d) |
-s | Stop a running background server |
--help | Show help for this command |
Service Management
cortex serve install # Install as a system service
cortex serve uninstall # Uninstall the system service
REST API Endpoints
The server exposes 85+ REST API endpoints across 20+ resource groups. Key endpoints include:
| Method | Path | Description |
|---|---|---|
| GET | /api/health | Health check |
| GET | /api/sessions | List recent sessions |
| GET | /api/sessions/tree | Session hierarchy tree |
| GET | /api/sessions/:id | Get session details |
| GET | /api/sessions/:id/events | Get session events |
| GET | /api/sessions/:id/messages | Get session messages |
| POST | /api/sessions/:id/resume | Resume a session |
| DELETE | /api/sessions/:id | Delete a session |
| GET | /api/memory/search?q=<query> | Search memory |
| POST | /api/memory/add | Add memory entry |
| GET | /api/jobs | List jobs by status |
| GET | /api/config | Get system configuration |
| GET | /api/providers/configured | List configured providers |
| GET | /api/lens/recent | Recent audit events |
| GET | /api/skills | List skill modules |
| GET | /api/plugins | List installed plugins |
| GET | /api/agents | List agent configurations |
| GET | /api/metrics | Prometheus metrics |
WebSocket Protocol
Connect to ws://<host>:<port>/ws for real-time streaming chat.
Client → Server messages:
{ "type": "chat", "message": "...", "sessionId": "sess_..." }
{ "type": "ping" }
{ "type": "new_session" }
{ "type": "select_agent", "agentId": "..." }
Server → Client messages:
{ "type": "connected" }
{ "type": "session", "sessionId": "sess_..." }
{ "type": "start" }
{ "type": "chunk", "delta": "..." }
{ "type": "done", "tokensIn": 100, "tokensOut": 50, "costUsd": 0.001, "durationMs": 800 }
{ "type": "error", "error": "..." }
{ "type": "pong" }
Web UI Dashboard
The built-in web UI provides a full-featured dashboard with these tabs:
- Dashboard — KPI cards, server info, system resources, daemon status
- Chat — WebSocket-powered streaming chat interface
- Sessions — Browse and manage all chat sessions
- Memory — Search and browse memory entries across all tiers
- Skills — Manage and browse skill modules
- Soul — Agent personality management
- Activity — Cortex Lens audit timeline of all tool calls and policy decisions
- Editor — Code editor with syntax highlighting
- Code Runner — Sandboxed code execution interface
- Version Control — Git workspace management (status, log, diff, commit, push)
- Projects — Project management
- Agents — Configure and manage agent profiles
- Services — Manage micro-service instances
- Nodes — Distributed node management and metrics
- Jobs — View scheduled job status and history
- Automation — Trigger and hook configuration
- Channels — Communication channel management
- Settings — System configuration
- Policies — Security policy rule management
- Extensions — Plugin installation and management (with marketplace sub-tab)
- Analytics — Usage and performance analytics
- Quartermaster — Model Quartermaster stats and dashboard
Session resume is supported: including an existing sessionId in a chat message reopens the per-session database and loads previous history.
Examples
# Start server on default port in foreground
cortex serve
# Start on a custom port in background
cortex serve --port 8080 --host 0.0.0.0 -d
# Restart a background server
cortex serve -d -r
# Stop the background server
cortex serve -s