{"id":50422983,"url":"https://github.com/orchestrator-dev/octo","last_synced_at":"2026-05-31T09:04:15.716Z","repository":{"id":339049007,"uuid":"1159549898","full_name":"orchestrator-dev/octo","owner":"orchestrator-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-20T22:36:31.000Z","size":5470,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-21T04:21:12.176Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orchestrator-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T21:32:17.000Z","updated_at":"2026-02-21T01:44:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/orchestrator-dev/octo","commit_stats":null,"previous_names":["vsmanu/octo","orchestrator-dev/octo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/orchestrator-dev/octo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrator-dev%2Focto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrator-dev%2Focto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrator-dev%2Focto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrator-dev%2Focto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orchestrator-dev","download_url":"https://codeload.github.com/orchestrator-dev/octo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrator-dev%2Focto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33725062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T09:04:13.982Z","updated_at":"2026-05-31T09:04:15.705Z","avatar_url":"https://github.com/orchestrator-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐙 Octo\n**The Intelligent, Distributed HTTP Monitoring Platform**\n\n![Octo Banner](assets/banner.png)\n\n[![Go Version](https://img.shields.io/badge/go-1.22+-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/license-AGPLv3-blue.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)\n[![Status](https://img.shields.io/badge/status-active-success.svg)](#)\n\nOcto is a modern, high-performance monitoring solution designed for developers and SREs who need reliability without the bloat. Built with **Go**, **React**, and **TimescaleDB**, Octo delivers real-time insights, historical analysis, and seamless configuration management in a lightweight package.\n\n---\n\n## 🚀 Key Features\n\n*   **⚡ High-Performance Monitoring**: Execute thousands of concurrent checks with minimal resource footprint.\n*   **📊 Real-Time Dashboard**: Visualize uptime, latency, and health status instantly via a modern React UI.\n*   **🔒 SSL/TLS Monitoring**: Automatically track certificate expiration and get alerted before they expire.\n*   **💾 Long-Term Storage**: Leverage **TimescaleDB** for powerful time-series queries and historical data retention.\n*   **⚙️ UI-Based Configuration**: manage your endpoints directly from the browser with a full-featured editor.\n*   **🚨 Alerting System**: Flexible alerting via Webhooks (Slack, Discord, PagerDuty) with tag-based routing.\n*   **🛠️ Hot-Reload**: Update your monitoring targets on the fly via API or UI—no restarts required.\n*   **🐳 Container Native**: Deploy effortlessly with Docker or Podman.\n*   **🌍 Multi-Satellite Monitoring**: Run distributed checks from multiple geographic locations to verify global availability and latency.\n*   **🤖 AI-Ready (MCP)**: Native integration with the Model Context Protocol (MCP) to allow AI agents to manage and query Octo.\n*   **👥 Multi-User \u0026 RBAC**: Secure local authentication with `admin` and `viewer` roles to protect your configuration.\n\n---\n\n## 🌍 Multi-Satellite Monitoring (New!)\n\nOcto now supports **Distributed Monitoring** via Satellites. Deploy lightweight satellite nodes in different regions (e.g., AWS us-east-1, DigitalOcean fra1) to:\n*   **Verify Global Availability**: Ensure your service is accessible from around the world.\n*   **Monitor Latency**: Track response times from different geographic edge locations.\n*   **Geo-Redundancy**: Avoid false positives caused by local network issues.\n\n### Satellite Configuration\nEasily assign endpoints to specific satellites via the configuration UI or YAML.\n![Satellite Config](/home/manu/.gemini/antigravity/brain/349300b6-f128-449e-ac40-a91e3509fed3/satellite_config.png)\n\n### Global Health View\nSee the status of your endpoints from every active satellite directly on the dashboard.\n![Dashboard Details](/home/manu/.gemini/antigravity/brain/349300b6-f128-449e-ac40-a91e3509fed3/dashboard_endpoint_details.png)\n\n---\n\n## 🤖 AI Integration via MCP\n\nOcto is designed to be fully **AI-Friendly**. The master node comes with an embedded **Model Context Protocol (MCP)** server, making it trivial to connect your monitoring data directly into AI assistants like Claude Desktop, Cursor, and custom agentic workflows.\n\nThe MCP server runs on the same port as the Octo API via Server-Sent Events (SSE).\n\n**Connection Details:**\n*   **Endpoint:** `http://localhost:8080/api/v1/mcp/sse`\n*   **Protocol:** SSE transport mapping to JSON-RPC messages\n\n**Available AI Tools:**\n*   `get_config`: Retrieve the deep metrics threshold and alerting configuration.\n*   `list_endpoints`: Fetch real-time status and information on all monitored endpoints.\n*   `list_satellites`: Get uptime and lifecycle metadata for all connected satellites.\n\n**Why Use MCP?**\nInstead of manually diagnosing an outage, your AI agent can query Octo to say *\"Which endpoints are currently offline?\"* or *\"Compare the latency of api.example.com across all satellites.\"*\n\n---\n\n## 📸 Screenshots\n\n### Operational Dashboard\nGet a bird's-eye view of all your services with real-time status indicators.\n![Dashboard](assets/dashboard.png)\n\n### Deep Dive Analytics \u0026 SSL Info\nAnalyze historical performance trends, view SSL certificate details, and spot anomalies with synchronized charts.\n![Details](/home/manu/.gemini/antigravity/brain/474e469c-9b7c-4452-bdbf-4167263b6816/endpoint_details_verification_1771347979164.png)\n\n### Endpoint Management\nEffortlessly add, edit, and remove endpoints using the built-in configuration editor.\n![Configuration](/home/manu/.gemini/antigravity/brain/474e469c-9b7c-4452-bdbf-4167263b6816/endpoints_list_gear_icons_final_1771349462941.png)\n\n### Powerful Editor\nConfigure advanced settings like Request Headers, Validation Rules, and SSL Alerts with ease.\n![Editor](/home/manu/.gemini/antigravity/brain/474e469c-9b7c-4452-bdbf-4167263b6816/filled_endpoint_form_bottom_1771349992199.png)\n\n---\n\n## 🏗️ Architecture\n\nOcto follows a clean, modular architecture separating the core monitoring engine from the storage and presentation layers.\n\n```mermaid\ngraph TD\n    User[\"User / Browser\"] --\u003e|\"HTTP/WebSockets\"| API[\"API Server (Go)\"]\n    API --\u003e|\"Serve UI\"| UI[\"React Frontend\"]\n    API --\u003e|\"Read/Write\"| Config[\"Config Manager\"]\n    Config --\u003e|Load| SCH[Scheduler]\n    SCH --\u003e|Spawn| Workers[\"Worker Pool\"]\n    Workers --\u003e|\"HTTP Check\"| Target[\"External Targets\"]\n    Workers --\u003e|\"Store Result\"| DB[(\"TimescaleDB\")]\n    API --\u003e|\"Query Metrics\"| DB\n    \n    subgraph Core Engine\n        Config\n        SCH\n        Workers\n    end\n\n    subgraph Satellites [\"Distributed Satellites\"]\n        Sat1[\"Satellite (US-East)\"]\n        Sat2[\"Satellite (EU-West)\"]\n    end\n\n    Sat1 --\u003e|\"Poll Config / Push Results\"| API\n    Sat2 --\u003e|\"Poll Config / Push Results\"| API\n    Sat1 --\u003e|\"HTTP Check\"| Target\n    Sat2 --\u003e|\"HTTP Check\"| Target\n```\n\n---\n\n## ⚙️ Configuration\nOcto uses a YAML configuration file located at `config/config.yml`.\n\n### Volume Mounting\nWhen running with Docker or Podman, the local `config/` directory is mounted into the container at `/config`.\nThis means you can edit `config/config.yml` on your host machine, and the changes will be reflected in the container (requires restart for some changes, though hot-reload is supported for endpoints).\n\n**Note:** The `config.yml` file is NOT baked into the image. It is injected at runtime via the volume mount.\n\n---\n\n## 🔐 Authentication \u0026 Users\n\nOcto supports local authentication with Role-Based Access Control (RBAC). You can define multiple users with different roles (`admin` or `viewer`).\n\n### Generating Passwords\nPasswords are secured using `bcrypt`. To generate a hashed password for your `config.yml`, use the included `hashpass` utility.\nFrom the project root, run:\n```bash\ngo run cmd/hashpass/main.go\n# Or if built:\n./bin/hashpass\n```\n\n### Example `config.yml` Auth Section\n```yaml\nauth:\n  enabled: true\n  provider: \"local\"\n  secret: \"your-super-secret-jwt-key\"\n  users:\n    - username: \"admin\"\n      password_hash: \"$2a$10$...\" # Output from hashpass\n      role: \"admin\"\n    - username: \"viewer\"\n      password_hash: \"$2a$10$...\"\n      role: \"viewer\"\n```\n*   **Admin**: Can view dashboards, metrics, and manage the configuration (add/edit/delete endpoints).\n*   **Viewer**: Can only view dashboards and metrics (read-only mode).\n\n\u003e [!NOTE]\n\u003e If `auth.enabled` is `true` but you omit the `users` list entirely, Octo will safely inject a default admin user with the credentials:\n\u003e **username**: `admin`\n\u003e **password**: `admin`\n\n---\n\n## 🗺️ Project Roadmap\n\n| Version | Status | Features |\n| :--- | :--- | :--- |\n| **v0.1.0** | ✅ **Released** | MVP Core Engine, InfluxDB Support, Basic API |\n| **v0.2.0** | ✅ **Released** | React Frontend, TimescaleDB Migration, Config UI, Historical Charts |\n| **v0.3.0** | ✅ **Released** | Alerting Engine, SSL Monitoring, Config Editor, Aggregation Metrics |\n| **v0.4.0** | ✅ **Released** | User Authentication (Local/Basic), Multi-user Support, RBAC |\n| **v1.0.0** | 📅 **Future** | High Availability Clustering, Plugin System, Public Release |\n\n---\n\n## 🏁 Getting Started\n\n### Prerequisites\n*   **Docker** or **Podman**\n*   **Go 1.22+** (only for manual builds)\n\n### 🚀 Quick Start (Pre-built Docker Image)\nThe absolute easiest way to get up and running is to use the official pre-built image from the GitHub Container Registry:\n\n```bash\ndocker pull ghcr.io/orchestrator-dev/octo-master:latest\ndocker run -d -p 8080:8080 -v $(pwd)/config:/config ghcr.io/orchestrator-dev/octo-master:latest\n```\nOpen **[http://localhost:8080](http://localhost:8080)** to start monitoring.\n\n---\n\n### ⚡ Develop Locally (Podman)\nA fast way to get up and running if you have Podman installed:\n\n```bash\n./scripts/run_podman.sh\n```\n\n### 🐳 Develop Locally (Docker Compose)\nStandard deployment for Docker users building from source:\n\n```bash\ndocker-compose up -d --build\n```\n\n### 🔧 Manual Setup\nFor development or custom deployments:\n\n1.  **Start Database**: Ensure TimescaleDB is running on `localhost:5432`.\n2.  **Build \u0026 Run**:\n    ```bash\n    # Build Frontend\n    cd web \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 cd ..\n\n    # Build Backend\n    go build -o master cmd/master/main.go\n\n    # Run\n    ./master\n    ```\n\n---\n\n## 📡 API Reference\n\nOcto exposes a RESTful API for automation and integration.\n\n*   `GET /health` - System health check\n*   `GET /api/v1/config` - Retrieve current configuration\n*   `POST /api/v1/config/endpoints` - Create new endpoint\n*   `GET /api/v1/endpoints` - List all endpoints\n*   `GET /api/v1/endpoints/{id}/history` - Retrieve historical metrics\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by the Octo Team\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forchestrator-dev%2Focto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forchestrator-dev%2Focto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forchestrator-dev%2Focto/lists"}