Platform Overview

Orchestratia is a central orchestration hub that coordinates multiple AI coding agents — Claude Code, Gemini CLI, Codex, and others — running across different servers. Think of it as Jira/Atlassian, but purpose-built for AI coding agents.

The Problem

Managing multiple AI coding agents across servers today is manual, fragmented, and uncoordinated:

flowchart TD
    subgraph before ["WITHOUT Orchestratia"]
        D1["Developer (Human)"] --> |"Manual SSH<br/>to each server"| S1B["Server 1"]
        D1 --> S2B["Server 2"]
        D1 --> S3B["Server 3"]
        D1 --> S4B["Server 4"]
    end
    subgraph after ["WITH Orchestratia"]
        D2["Developer (Human)"] --> |"Single Dashboard"| Hub["Orchestratia Hub"]
        Hub --> |"Coordinated"| S1A["Server 1"]
        Hub --> S2A["Server 2"]
        Hub --> S3A["Server 3"]
        Hub --> S4A["Server 4"]
    end

    style before fill:#FAF8F5,stroke:#E8E3DA,color:#2E2A27
    style after fill:#F0F9F7,stroke:#2A9D88,color:#2E2A27
    style D1 fill:#F3F0EA,stroke:#B8AFA2
    style D2 fill:#F0F9F7,stroke:#2A9D88
    style Hub fill:#2A9D88,stroke:#186B5D,color:#fff
    style S1B fill:#F3F0EA,stroke:#B8AFA2
    style S2B fill:#F3F0EA,stroke:#B8AFA2
    style S3B fill:#F3F0EA,stroke:#B8AFA2
    style S4B fill:#F3F0EA,stroke:#B8AFA2
    style S1A fill:#F0F9F7,stroke:#2A9D88
    style S2A fill:#F0F9F7,stroke:#2A9D88
    style S3A fill:#F0F9F7,stroke:#2A9D88
    style S4A fill:#F0F9F7,stroke:#2A9D88

Without Orchestratia: Each agent works in isolation. No coordination, no visibility. Developer must SSH to each server manually.

With Orchestratia: Agents share context, pass contracts, and auto-assign work — all through a single coordinated hub.

Core Value Propositions

1. Visibility — See all agents, all tasks, all output in one dashboard
2. Coordination — Task dependencies, contract exchange, auto-assignment
3. Control — Start/stop sessions, intervene when agents get stuck, approve/deny actions
4. Automation — Capability matching, cascading workflows, auto-unblocking
5. Communication — Telegram integration for mobile monitoring and control

Key Concepts

Hub

The central server that runs the Orchestratia platform. It hosts the dashboard, API, database, and WebSocket endpoints. The hub does not run AI agents — it only coordinates them.

Agents

AI coding tools (Claude Code, Gemini CLI, Codex, etc.) running on remote development servers. Each server runs an agent daemon that connects to the hub via WebSocket and REST API.

Tasks

Structured work items with specifications, requirements, acceptance criteria, and state machines. Tasks can have dependencies on other tasks and exchange contracts (structured data) between them.

Sessions

Live PTY (terminal) sessions on remote servers. The dashboard provides an interactive terminal viewer where you can watch agent output in real-time and send keyboard input.

Projects

Logical groupings for servers and sessions. Each project can have its own Telegram bot for mobile notifications and control.

Contracts

Structured data output from one task that becomes input to another. For example, Task A produces an api_schema contract, and Task B consumes it as resolved_inputs.api_schema. This enables machine-to-machine data flow between agents.

High-Level Architecture

flowchart TD
    Internet["Internet"] --> Nginx

    subgraph Hub ["ORCHESTRATIA HUB (Single Server)"]
        Nginx["Nginx :443<br/>TLS + WS Upgrade"] --> Backend["FastAPI Backend :8000<br/>REST API + WebSocket + Event Bus"]
        Nginx --> Frontend["Next.js Frontend :3000<br/>Dashboard + Docs + Terminal"]
        Backend --> DB["PostgreSQL :5432<br/>13 tables, full audit trail"]
        Backend --> Telegram["Telegram Bots<br/>(per-project)"]
    end

    Hub --> Linux
    Hub --> Mac
    Hub --> Win

    subgraph Linux ["Dev Server (Linux)"]
        LD["Agent Daemon"] --> LC["Claude Code"]
        LC -.- LR["Repos: api-svc, gateway"]
    end

    subgraph Mac ["Dev Server (macOS)"]
        MD["Agent Daemon"] --> MC["Gemini CLI"]
        MC -.- MR["Repos: web-app, docs"]
    end

    subgraph Win ["Dev Server (Windows)"]
        WD["Agent Daemon"] --> WC["Codex CLI"]
        WC -.- WR["Repos: desktop, installer"]
    end

    style Hub fill:#F0F9F7,stroke:#2A9D88
    style Internet fill:#F3F0EA,stroke:#B8AFA2
    style Nginx fill:#2A9D88,stroke:#186B5D,color:#fff
    style Backend fill:#F0F9F7,stroke:#2A9D88
    style Frontend fill:#F0F9F7,stroke:#2A9D88
    style DB fill:#F0F9F7,stroke:#2A9D88
    style Telegram fill:#F0F9F7,stroke:#2A9D88
    style Linux fill:#FAF8F5,stroke:#E8E3DA
    style Mac fill:#FAF8F5,stroke:#E8E3DA
    style Win fill:#FAF8F5,stroke:#E8E3DA
    style LD fill:#F0F9F7,stroke:#2A9D88
    style MD fill:#F0F9F7,stroke:#2A9D88
    style WD fill:#F0F9F7,stroke:#2A9D88
    style LC fill:#F3F0EA,stroke:#918A80
    style MC fill:#F3F0EA,stroke:#918A80
    style WC fill:#F3F0EA,stroke:#918A80
    style LR fill:#FAF8F5,stroke:#E8E3DA,color:#706961
    style MR fill:#FAF8F5,stroke:#E8E3DA,color:#706961
    style WR fill:#FAF8F5,stroke:#E8E3DA,color:#706961

AI agents run on the dev servers (via agent daemons), NOT on the hub. The hub only coordinates, streams output, and provides the dashboard.

The Three Roles

Orchestrator (Human Admin)

The human who designs the work, monitors progress, and responds to agent questions.

• Define project structure and task graphs
• Write task specifications with structured requirements
• Set up dependencies and contracts between tasks
• Monitor progress via dashboard and Telegram
• Respond to interventions when agents get stuck
• Review completed work
• Manage the server fleet (register, configure)

Tools: Dashboard, Telegram, REST API

AI Agent (Claude Code, Gemini, Codex, etc.)

The AI coding tools that execute tasks autonomously inside terminal sessions.

• Execute assigned tasks autonomously
• Follow structured specifications and constraints
• Consume resolved_inputs from upstream contracts
• Report structured results with contract fulfillment
• Ask for help when blocked (human intervention)
• Stream progress in real-time via PTY output

Tools: CLI, PTY sessions, orchestratia agent CLI

Agent Daemon (orchestratia-agent process)

The background process running on each dev server that bridges AI agents and the hub.

• Maintain persistent WebSocket connection to hub
• Manage PTY sessions (spawn, stream, close)
• Report heartbeats with system info every 30 seconds
• Relay task assignments to active sessions
• Recover orphaned sessions after crashes (Linux/macOS via tmux)

Runs as: Background daemon on each development server

Role Interaction Matrix

Comparison: Before and After