@vibe-orchestrator/server

The VPS-side server for Vibe Orchestrator. Manages kanban state, routes agent tasks, and exposes MCP + REST + SSE + WebSocket endpoints.

Installation

npm install -g vibe-orchestrator

Or run from source:

cd packages/server
bun run dev

CLI Commands

vibe-orchestrator (or bun run src/index.ts)

Start the server. On first run, generates a config file and API key.

| Flag | Env Variable | Default | Description | |------|-------------|---------|-------------| | -p, --port | VIBE_PORT | 4242 | Server listen port | | -d, --data-dir | VIBE_DATA_DIR | ~/.vibe-orchestrator | Data directory |

First Run

=========================================
  Vibe Orchestrator MCP Server
=========================================
  Port:       4242
  Data dir:   /home/user/.vibe-orchestrator
  Health:     http://localhost:4242/health
  MCP:        http://localhost:4242/mcp
  WS:         ws://localhost:4242/ws
  API Key:    a1b2c3d4...
  (Save this key - it will not be shown again)
=========================================

Data Directory Structure

~/.vibe-orchestrator/         (or /var/lib/vibe-orchestrator/ on VPS)
  config.json                 Server configuration + hashed API key
  projects/
    <project-name>.db         SQLite database per project

API Endpoints

Health (Public -- no auth)

| Method | Path | Description | |--------|------|-------------| | GET | /health | Server health, uptime, active sessions, executor status |

MCP (Bearer token auth)

| Method | Path | Description | |--------|------|-------------| | POST | /mcp | MCP Streamable HTTP transport endpoint |

WebSocket (API key in query param)

| Path | Description | |------|-------------| | ws://host:4242/ws?key=API_KEY | Executor WebSocket connection |

REST API (Bearer token or vibe-key cookie)

Authentication

| Method | Path | Description | |--------|------|-------------| | GET | /api/auth?key=API_KEY | Set auth cookie and redirect to /board |

Board & Tickets

| Method | Path | Description | |--------|------|-------------| | GET | /api/board/:project | Get kanban board tree (optional ?status= filter) | | GET | /api/ticket/:id | Get single ticket details | | POST | /api/ticket/:id/move | Move ticket to new status { "status": "..." } |

Sessions

| Method | Path | Description | |--------|------|-------------| | GET | /api/sessions | List sessions (optional ?project= filter) | | GET | /api/sessions/:id | Get session details | | GET | /api/sessions/:id/logs | Get session logs (?offset=0&limit=100) |

Swarms

| Method | Path | Description | |--------|------|-------------| | GET | /api/swarms | List swarms (optional ?project= filter) | | GET | /api/swarm/:id | Get swarm status | | GET | /api/swarm/:id/messages | Get swarm messages (optional ?since=timestamp) |

Other

| Method | Path | Description | |--------|------|-------------| | POST | /api/tickets/generate | AI ticket generation { "prompt": "...", "projectId": "..." } | | GET | /api/executor/status | Check executor connection status |

SSE (Server-Sent Events)

| Path | Description | |------|-------------| | GET /api/events | Real-time event stream |

SSE event types:

| Event | Payload | Description | |-------|---------|-------------| | connected | { ts } | Initial connection confirmation | | heartbeat | { ts } | Keep-alive every 30 seconds | | ticket_created | ticket object | New ticket created | | ticket_moved | ticket object | Ticket status changed | | ticket_updated | ticket object | Ticket fields updated | | swarm_message | swarm message | Message from swarm bus | | session_ended | { sessionId, exitCode, result? } | Agent session completed | | session_error | { sessionId, error } | Agent session errored | | executor_disconnected | { ts } | Executor lost connection |

Authentication

All API and MCP endpoints require authentication via one of:

1. Bearer token -- Authorization: Bearer YOUR_API_KEY header
2. HttpOnly cookie -- vibe-key cookie (set via /api/auth?key=...)

The API key is generated on first server start. The server stores only the SHA-256 hash. To rotate the key, delete config.json and restart.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | VIBE_PORT | 4242 | Server listen port | | VIBE_DATA_DIR | ~/.vibe-orchestrator | Data directory path | | NODE_ENV | development | Set to production on VPS |

VPS Deployment

Use the included deployment scripts:

# First-time VPS setup (as root):
bash scripts/deploy/setup-vps.sh

# Deploy from local machine:
bash scripts/deploy/deploy.sh your-vps.example.com root

The setup script installs Bun, Nginx, certbot, creates a systemd service, and configures reverse proxy with WebSocket support.

Development

bun run dev          # Start in dev mode
bun run test         # Run unit + integration tests
bun run db:generate  # Generate Drizzle migrations
bun run db:migrate   # Run migrations