Spaces:

Jishnupg
/

Opencode-Cli

Running

Hermes Agent

feat: completely remove Open WebUI and streamline multi-service container hub

58d7eda about 2 months ago

7.24 kB

---
title: Opencode CLI
emoji: 🖥️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 4096
pinned: false
---
<div align="center">

# 🚀 OpenCode CLI & Multi-Service AI Gateway

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/Docker-ContainerIZED-blue.svg)](https://www.docker.com/)
[![Python](https://img.shields.io/badge/Python-3.11-3776AB.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688.svg)](https://fastapi.tiangolo.com/)
[![Node.js](https://img.shields.io/badge/Node.js-v20-339933.svg)](https://nodejs.org/)
[![Next.js](https://img.shields.io/badge/Next.js-v16-000000.svg)](https://nextjs.org/)

[Features](#-key-features) • [Architecture](#-architecture) • [Port Matrix](#-port--ingress-matrix) • [Quick Start](#-quick-start) • [Client Setup](#-client-integration-guides) • [Documentation](#-documentation)

</div>

---

## 🌟 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

```mermaid
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
```python
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:
```bash
# 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](https://www.docker.com/) & Docker Compose
- Environment file (`.env`)

### Running with Docker Compose
```bash
# 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_ARCHITECTURE.md) — Hermes Agent Framework architecture, port matrix, and locking rules.
- 🧠 [`OMNIROUTE_INTEGRATION_PLAN.md`](OMNIROUTE_INTEGRATION_PLAN.md) — OmniRoute AI Gateway routing architecture.
- 🚀 [`DEPLOYMENT_GUIDE.md`](DEPLOYMENT_GUIDE.md) — Deployment and persistence guide.
- 🏗️ [`ARCHITECTURE.md`](ARCHITECTURE.md) — Multi-service system architecture overview.

---

## 📄 License

Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.


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

	<div align="center">

	# 🚀 OpenCode CLI & Multi-Service AI Gateway

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

	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
	[![Docker](https://img.shields.io/badge/Docker-ContainerIZED-blue.svg)](https://www.docker.com/)
	[![Python](https://img.shields.io/badge/Python-3.11-3776AB.svg)](https://www.python.org/)
	[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688.svg)](https://fastapi.tiangolo.com/)
	[![Node.js](https://img.shields.io/badge/Node.js-v20-339933.svg)](https://nodejs.org/)
	[![Next.js](https://img.shields.io/badge/Next.js-v16-000000.svg)](https://nextjs.org/)

	[Features](#-key-features) • [Architecture](#-architecture) • [Port Matrix](#-port--ingress-matrix) • [Quick Start](#-quick-start) • [Client Setup](#-client-integration-guides) • [Documentation](#-documentation)

	</div>

	---

	## 🌟 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

	```mermaid
	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
	```python
	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:
	```bash
	# 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](https://www.docker.com/) & Docker Compose
	- Environment file (`.env`)

	### Running with Docker Compose
	```bash
	# 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_ARCHITECTURE.md) — Hermes Agent Framework architecture, port matrix, and locking rules.
	- 🧠 [`OMNIROUTE_INTEGRATION_PLAN.md`](OMNIROUTE_INTEGRATION_PLAN.md) — OmniRoute AI Gateway routing architecture.
	- 🚀 [`DEPLOYMENT_GUIDE.md`](DEPLOYMENT_GUIDE.md) — Deployment and persistence guide.
	- 🏗️ [`ARCHITECTURE.md`](ARCHITECTURE.md) — Multi-service system architecture overview.

	---

	## 📄 License

	Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.