Quickstart

From zero to a running MCP server, talking to your LLM agent, in under a minute.

Step 1 — Install Orkestra and the agent skill

Option A (recommended): one-line remote install — no clone required

curl -fsSL https://raw.githubusercontent.com/Vijay431/Orkestra/main/install.sh | PROJECT_ID=myapp bash

Option B: clone and install locally

git clone https://github.com/Vijay431/Orkestra
cd Orkestra
PROJECT_ID=myapp ./install.sh

Either path does the same thing:

1. Clones (or updates) the repo to ~/.orkestra
2. Builds the Docker image and starts the server on :8080
3. Detects your IDE and registers the MCP server config
4. Installs the operator skill to ~/.agents/skills/orkestra/

The installer is idempotent — re-running it updates config in place.

What gets auto-configured

flowchart TD
    A[install.sh] --> B{Which IDE?}
    B -->|claude CLI present| C[Claude Code config]
    B -->|.vscode or .github| D[GitHub Copilot]
    B -->|cursor command| E[Cursor]
    B -->|~/.codeium/| F[Windsurf]
    B -->|~/.config/zed/| G[Zed]
    B -->|~/.continue/| H[Continue.dev]
    C --> I[MCP server registered]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I

Step 2 — Run the server

install.sh already started a Docker container. If you need to start it yourself:

Docker:

PROJECT_ID=myapp docker compose up -d

Manual / no Docker (Go 1.22+ required — useful for working on Orkestra itself):

PROJECT_ID=myapp DB_PATH=/tmp/dev.db go run ./cmd/server

Step 3 — Verify

curl http://localhost:8080/health
# → {"status":"ok","project":"myapp","db_ok":true,...}

Then, in your AI tool, ask: “Use ticket_backlog to show me my work queue.” You should see TOON/1 [...] come back — empty until you create tickets.

Environment variables

Variable	Default	What it does
PROJECT_ID	(required)	Ticket prefix and scope filter — every ID becomes {PROJECT_ID}-NNN
DB_PATH	/data/orkestra.db	SQLite file location
PORT	8080	HTTP listen port
BIND_ADDR	0.0.0.0	Listen address — set to 127.0.0.1 for localhost-only
MCP_TOKEN	(unset)	Bearer token for /sse and /message (optional auth)
LOG_LEVEL	info	debug · info · warn · error
BACKUP_DIR	/data/backups	Where periodic backups land
BACKUP_INTERVAL	1h	Go duration string (30m, 2h, 24h…)
BACKUP_KEEP	24	Backup retention count

Inspecting the database

sqlite3 /tmp/dev.db ".tables"
sqlite3 /tmp/dev.db "SELECT id, title, status, priority FROM tickets WHERE archived_at IS NULL;"

Or open it with DB Browser for SQLite.

Next: pick your workflow

• Core loop → the 3-tool agent loop
• Epics → spawn parallel subtask trees
• Sequential pipelines → enforce ordering with exec_mode=seq