README.md

metadata

title: Opencode CLI
emoji: 🖥️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 4096
pinned: false

🚀 OpenCode CLI & Multi-Service AI Gateway

Enterprise Multi-Service AI, Autonomous Agent, and Streaming Container Hub

Features • Architecture • Port Matrix • Quick Start • Client Setup • Documentation

---

🌟 Project Overview

OpenCode CLI is a production-grade, multi-service Docker container hub combining an OpenAI-compatible LLM router (OmniRoute), an autonomous self-improving AI agent (Hermes Agent), a media server (Jellyfin), and a high-speed video streamer (Telegram Drive Proxy), all orchestrated behind a unified FastAPI & Nginx reverse proxy with persistent storage synchronization.

---

🏗️ Architecture

graph TD
    Client[📱 Clients / Mobile APK / Web Browser / Telegram] -->|HTTPS :4096| Nginx[🌐 Nginx Reverse Proxy]
    Nginx -->|Proxy /| FastAPI[⚡ FastAPI Master Gateway :8000]

    FastAPI -->|Proxy /v1/*, /dashboard| OmniRoute[🧠 OmniRoute AI Gateway :20128]
    FastAPI -->|Proxy /hermes/*| Hermes[🤖 Hermes Agent Framework :8642]
    FastAPI -->|Proxy /jellyfin| Jellyfin[🎬 Jellyfin Server :8096]
    FastAPI -->|Proxy /tg-stream| TGStream[⚡ Telegram Streamer :8080]

    OmniRoute -->|LLM Backend| ExternalLLM[☁️ Cloud Providers / OpenAI / Anthropic / Gemini]
    Hermes -->|API Calling| OmniRoute

    subgraph Persistence Layer [/data Volume]
        OmniRouteDB[(storage.sqlite)]
        HermesMemory[(Hermes Memory & Skills)]
    end

    OmniRoute -.->|15s Snapshot| OmniRouteDB
    Hermes -.->|15s rsync| HermesMemory

---

✨ Key Features

🧠 1. OmniRoute AI Gateway (/v1, /dashboard)

• Multi-Provider Load Balancer: Route prompts across OpenAI, Anthropic, Gemini, DeepSeek, Groq, and custom endpoints.
• Model Fallback & Combos: Dynamic candidate pools and automatic retry failovers.
• Embedded Dashboard: Manage API keys, provider credentials, and token usage analytics.

🤖 2. Hermes Autonomous Agent Framework (/hermes/v1)

• Nous Research Engine: Autonomous tool-calling agent with native web search, web page extraction, and browser automation.
• Persistent Memory & Self-Improving Skills: Automatically learns user preferences (USER.md), facts (MEMORY.md), and generates python skills (skills/).
• OpenAI-Compatible Endpoint: Exposes /hermes/v1/chat/completions and /hermes/v1/models for mobile APKs, Termux, and OpenAI SDKs.

🎬 3. Jellyfin Media Server (/jellyfin/)

• Personal Media Streaming: Stream movies, TV shows, and audio directly from persistent storage.

⚡ 4. Telegram Stream Proxy (/tg-stream/)

• High-Speed Range Streamer: Stream video files directly from Telegram channels using chunked HTTP range requests.

🛡️ 5. Self-Healing & Persistence Supervisor

• PID 1 Supervisor: Auto-restarts any crashed background service within 5 seconds.
• Integrity Validation: Periodic background snapshotting to /data/ persistent volumes.

---

📊 Port & Ingress Matrix

Microservice	Internal Port	External Route	Status Health Check
Public Gateway	:4096 / :8000	/	GET /health/live
OmniRoute API & Dashboard	:20128	/v1/*, /dashboard	GET /v1/models
Hermes Agent Framework	:8642	/hermes/v1/*	GET /hermes/health
Jellyfin Media Server	:8096	/jellyfin/	GET /jellyfin/
Telegram Streamer	:8080	/tg-stream/	GET /tg-stream/health

---

📱 Client Integration Guides

1. Mobile Android APK / Custom Client Connection

Connect any OpenAI-compatible Android app or mobile UI to your personal Hermes agent:

• Base URL: https://jishnupg-opencode-cli.hf.space/hermes/v1
• API Key: <your HERMES_GATEWAY_API_KEY secret>
• Models Endpoint: https://jishnupg-opencode-cli.hf.space/hermes/v1/models
• Chat Completions: https://jishnupg-opencode-cli.hf.space/hermes/v1/chat/completions

2. Python OpenAI SDK

from openai import OpenAI

# Connect to Hermes Agent
client = OpenAI(
    base_url="https://jishnupg-opencode-cli.hf.space/hermes/v1",
    api_key="your_hermes_secret_key",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Search the web for latest AI news"}],
)

print(response.choices[0].message.content)

3. Local CLI / Termux (hermes setup)

To run Hermes CLI on your own device using your Space's OmniRoute backend:

# Install Hermes CLI
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Run interactive setup
hermes setup
# Select Provider: OpenAI-compatible
# Base URL: https://jishnupg-opencode-cli.hf.space/v1
# API Key: key_oute_xxxxxxxxxxxx

---

🚀 Quick Start (Local Docker Run)

Prerequisites

• Docker & Docker Compose
• Environment file (.env)

Running with Docker Compose

# Clone repository
git clone https://github.com/JishnuPG-tech/Project.git
cd Project

# Copy environment template
cp .env.example .env

# Build and launch container
docker compose up -d --build

Access the hub at http://localhost:4096.

---

🔐 Environment Variables & Secrets Reference

Variable	Description	Required
STORAGE_ENCRYPTION_KEY	Master key for database field encryption	Yes
OMNIROUTE_STORAGE_KEY	Storage encryption key for OmniRoute SQLite	Yes
JWT_SECRET	Secret token for JWT session signing	Yes
API_KEY_SECRET	Secret key for OmniRoute API keys	Yes
INITIAL_PASSWORD	Initial admin password for web interfaces	Yes
HERMES_MODEL	Default model for Hermes Agent (default: claude-sonnet-4-6)	Optional
TELEGRAM_BOT_TOKEN	Bot token for Telegram integration	Optional

---

📚 Documentation Reference

• 📄 HERMES_ARCHITECTURE.md — Hermes Agent Framework architecture, port matrix, and locking rules.
• 🧠 OMNIROUTE_INTEGRATION_PLAN.md — OmniRoute AI Gateway routing architecture.
• 🚀 DEPLOYMENT_GUIDE.md — Deployment and persistence guide.
• 🏗️ ARCHITECTURE.md — Multi-service system architecture overview.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.