OpenCode Multi-Instance Coordinator

A lightweight coordination platform for managing multiple OpenCode instances. Each node (home computer, office computer, etc.) runs an independent deployment with Web UI for local task management. Data is aggregated through Feishu Bitable for a global view.

This system solves the coordination challenges when running OpenCode on multiple machines. It provides a Web UI console for task submission, worker pool management, real-time progress tracking, and automatic Feishu progress synchronization.

• Web UI Console: Local deployment with localhost access
• Worker Pool Management: Support for heterogeneous environment registration
• Task Queue: Automatic task distribution to available workers
• Feishu Integration: Automatic progress backup and notifications
• Simple API Token Authentication: Suitable for internal or small team use
• Real-time Updates: WebSocket-based live status updates

The main dashboard provides an overview of all tasks with real-time WebSocket status, task state visualization, and filtering capabilities.

Create new tasks with a simple form. Tasks are automatically distributed to available workers.

View detailed information about each task including status, assigned worker, and execution timeline.

Quickly identify and review failed tasks for troubleshooting.

Each computer runs a complete, independent stack. No public server is required.

• Node.js 18+ and npm
• Python 3.10+
• Python package websocket-client (worker runtime imports websocket)
• OpenCode CLI installed
• Docker and Docker Compose (optional)

1. Clone and install dependencies

git clone <repository-url>
cd opencode-multi-instance-coordinator
npm install
npm --prefix server install
npm --prefix web install
python3 -m pip install websocket-client

2. Configure environment

cp .env.example .env
# Edit .env with your settings

3. Start all services locally

./scripts/start-local.sh

This starts:

• Backend API at http://localhost:3000
• Web UI at http://localhost:5173
• Worker process

4. Access the Web UI

Open http://localhost:5173 in your browser.

docker-compose.yml currently includes only backend + redis services; it does not start the Python worker. Start worker separately after compose is up.

# Start services
docker-compose up -d

# Start worker separately (uses worker/.env or process env)
python3 worker/main.py

# View logs
docker-compose logs -f backend

# Stop services
docker-compose down

.
├── web/                  # Frontend React application
│   ├── src/
│   │   ├── pages/       # Page components
│   │   ├── components/  # Reusable components
│   │   └── hooks/       # Custom React hooks
│   └── package.json
├── server/              # Backend Fastify application
│   ├── src/
│   │   ├── routes/      # REST API routes
│   │   ├── websocket/   # WebSocket handlers
│   │   ├── services/    # Business logic
│   │   └── middleware/  # Auth and other middleware
│   └── package.json
├── worker/              # Python worker daemon
│   ├── src/
│   │   ├── main.py      # Entry point
│   │   ├── config.py    # Configuration
│   │   ├── runtime.py   # WebSocket client
│   │   └── opencode.py  # OpenCode execution
│   └── main.py          # CLI entry point
├── scripts/             # Utility scripts
│   ├── start-local.sh   # Local development starter
│   └── stop-local.sh    # Local development stopper
├── docs/                # Documentation
│   ├── API.md          # API reference
│   ├── Worker.md       # Worker configuration
│   └── Development.md  # Development guide
├── docker-compose.yml   # Docker orchestration
└── package.json         # Root package configuration

Create a .env file in the project root:

# Server
PORT=3000
API_TOKEN=your-secret-token
CORS_ORIGIN=http://localhost:5173

# Web UI (Vite environment variables must be prefixed with VITE_)
VITE_SERVER_PORT=3000
VITE_API_TOKEN=your-secret-token

# Feishu Integration (optional)
FEISHU_APP_ID=your-app-id
FEISHU_APP_SECRET=your-app-secret
FEISHU_BITABLE_APP_TOKEN=your-app-token
FEISHU_BITABLE_TABLE_ID=your-table-id

# Worker
WORKER_WS_URL=ws://localhost:3000/ws/worker
WORKER_TOKEN=your-secret-token
WORKER_ID=worker-local-1
WORKER_NAME=Local Worker

See .env.example for the complete list of configuration options.

• API Reference - REST API endpoints and WebSocket protocol
• Worker Configuration - Worker setup and environment requirements
• Development Guide - Development setup, testing, and troubleshooting

1. Create: User creates a task via Web UI or API
2. Queue: Task enters waiting queue if no worker is immediately available
3. Assign: Scheduler assigns task to an available worker using load-balanced round-robin
4. Execute: Worker executes the task using OpenCode CLI
5. Sync: Progress is streamed in real-time to the Web UI
6. Complete: Task result is synced to Feishu Bitable

The scheduler uses a load-balanced round-robin algorithm:

1. Workers are sorted by current load (number of assigned tasks)
2. Among workers with the lowest load, round-robin selection is applied
3. When a worker disconnects, its tasks are returned to the waiting queue
4. When a new worker connects, pending tasks are automatically reassigned

• API endpoints (except /health) require Bearer token authentication
• WebSocket connections for workers require registration with valid credentials
• All services bind to localhost by default in local development mode
• No public internet exposure required

MIT License - see LICENSE file for details.

See Development Guide for setup instructions and contribution guidelines.