# APEX OS Tool Registry > **The authoritative registry of all tools, services, and platforms deployed in APEX OS.** > This document tracks every tool's purpose, status, lifecycle stage, and certification history. > New tools must pass the certification process defined herein before production deployment. **Version:** 2.0 **Last Updated:** Phase 7 — CEO Command Center **Classification:** CORE — Updated whenever tools are added, updated, or retired **Maintainer:** Engineer (#1) **Cross-references:** [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md) · [APEX_CONSTITUTION.md](APEX_CONSTITUTION.md) --- ## Table of Contents - [1. Purpose](#1-purpose) - [2. Tool Categories](#2-tool-categories) - [3. Current Tool Registry](#3-current-tool-registry) - [3.1 Infrastructure](#31-infrastructure) - [3.2 AI/ML Platform](#32-aiml-platform) - [3.3 Development Tools](#33-development-tools) - [3.4 Monitoring & Observability](#34-monitoring--observability) - [3.5 Security](#35-security) - [3.6 Automation & Communication](#36-automation--communication) - [3.7 Management](#37-management) - [3.8 Custom Services](#38-custom-services) - [4. Evaluation Criteria](#4-evaluation-criteria) - [5. Certification Process](#5-certification-process) - [6. Lifecycle Stages](#6-lifecycle-stages) - [7. Security Review Requirements](#7-security-review-requirements) - [8. Sandbox Testing Protocol](#8-sandbox-testing-protocol) - [9. Promotion Process](#9-promotion-process) - [10. Retirement Process](#10-retirement-process) - [11. Update Strategy](#11-update-strategy) - [12. Resource Budget](#12-resource-budget) - [13. Integration Map](#13-integration-map) - [14. Change History](#14-change-history) --- ## 1. Purpose APEX OS uses a **curated set of tools** — each evaluated, certified, and monitored. This registry serves as: - **Inventory** — What tools are deployed, their versions, and their purpose - **Governance** — How tools are evaluated, adopted, and retired - **Operations** — Container names, ports, and network configuration for each tool - **Standards** — The quality bar every tool must meet before production deployment No tool enters production without passing the certification process. No tool remains in production without ongoing maintenance and monitoring. --- ## 2. Tool Categories | Category | Description | Examples | |----------|-------------|---------| | **Infrastructure** | Core platform services — networking, data, compute | Docker, Traefik, PostgreSQL, Redis | | **AI/ML** | Artificial intelligence and machine learning services | LiteLLM, Ollama, Letta, Open WebUI | | **Development** | Code hosting, IDEs, and development workflows | Gitea, Code-Server | | **Monitoring** | System health, metrics, logs, and tracing | Grafana, Prometheus, Loki, Langfuse | | **Security** | Credential management, access control, network security | Vaultwarden, Docker Socket Proxy | | **Automation** | Workflow automation and communication | n8n, Telegram Bot | | **Management** | Container and infrastructure management UIs | Dockge | | **Custom** | APEX OS-specific services built in-house | APEX Status API | --- ## 3. Current Tool Registry ### 3.1 Infrastructure | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **Docker** | 24.x | Host | — | ✅ Production | Maintenance | Container runtime engine. All APEX OS services run as Docker containers. | | **Traefik** | v3.x | `apex-traefik` | 80, 443 | ✅ Production | Maintenance | Reverse proxy with automatic Let's Encrypt SSL certificate management. Routes `*.apex.unstuck-path.com` subdomains to containers via Docker labels. | | **PostgreSQL** | 16.x | `apex-postgres` | 5432 | ✅ Production | Maintenance | Primary relational database. Hosts schemas: `apex` (company data), `mem0` (knowledge), `letta` (agents). Includes `pgvector` extension for HNSW-indexed vector similarity search (cosine). | | **Redis** | 7.x | `apex-redis` | 6379 | ✅ Production | Maintenance | In-memory cache and message queue. Used for LLM response caching, session management, and inter-service message passing. | ### 3.2 AI/ML Platform | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **LiteLLM** | latest | `apex-litellm` | 4000 | ✅ Production | Maintenance | Unified LLM proxy. Routes requests to OpenRouter (GPT-4o, Claude 3.5 Sonnet) and Ollama (local models). Provides a single `/v1/chat/completions` endpoint for all employees. Tracks token usage and costs. | | **Ollama** | latest | `apex-ollama` | 11434 | ✅ Production | Maintenance | Local model runtime. Serves `phi3:mini` (3.8B, routine reasoning) and `nomic-embed-text` (embeddings for vector search). Zero-cost inference for routine tasks. | | **Letta** | 0.16.x | `apex-letta` | 8283 | ✅ Production | Maintenance | Agent framework providing persistent memory, tool use, and structured agent management. Hosts all 6 APEX OS employee agents. Uses PostgreSQL backend for agent state. | | **Open WebUI** | latest | `apex-openwebui` | 8080 | ✅ Production | Maintenance | Web-based chat interface for interactive LLM conversations. Connected to LiteLLM for model access. Provides human-friendly UI for testing and ad-hoc queries. | **Model Registry (Ollama):** | Model | Parameters | Size | Purpose | Routing | |-------|-----------|------|---------|---------| | `phi3:mini` | 3.8B | ~2.3 GB | Routine reasoning, summarization, classification | Default for simple tasks | | `nomic-embed-text` | 137M | ~274 MB | Text embeddings for vector search | All embedding operations | **Model Registry (OpenRouter):** | Model | Provider | Purpose | Cost (approx.) | Routing | |-------|----------|---------|----------------|---------| | `gpt-4o` | OpenAI | Complex reasoning, code generation, multi-step tasks | ~$5/1M tokens | Complex tasks via LiteLLM | | `claude-3.5-sonnet` | Anthropic | Creative writing, nuanced analysis, long-form content | ~$3/1M tokens | Creative tasks via LiteLLM | ### 3.3 Development Tools | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **Gitea** | 1.26.x | `apex-gitea` | 3000 | ✅ Production | Maintenance | Self-hosted Git server. Hosts 8+ repositories under the `engineer/` organization. Provides web UI, API access, and webhook integrations. Accessible at `git.apex.unstuck-path.com`. | | **Code-Server** | 4.126.x | `apex-code-server` | 8443 | ✅ Production | Maintenance | Web-based VS Code IDE. Provides browser-based code editing. Mounted with restricted access to `/opt/apex/config` and `/opt/apex/data` only (hardened in Phase 1). Accessible at `code-server.apex.unstuck-path.com`. | **Gitea Repository Inventory:** | Repository | Purpose | Status | |------------|---------|--------| | `engineer/apex-os-docs` | System documentation (this repository) | Active | | `engineer/apex-test-repo` | Integration testing | Active | | `engineer/engineer-workspace` | Engineer agent workspace | Active | | `engineer/research-workspace` | Research Analyst workspace | Active | | `engineer/marketing-workspace` | Marketing Strategist workspace | Active | | `engineer/documentation-workspace` | Documentation Agent workspace | Active | | `engineer/apex-status-api` | Custom health monitoring service | Active | | `engineer/apex-scripts` | Shared scripts and utilities | Active | ### 3.4 Monitoring & Observability | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **Grafana** | latest | `apex-grafana` | 3000 | ✅ Production | Maintenance | Dashboard and visualization platform. Hosts the 12-panel Executive Dashboard (UID: `a5jdct`) with system health, task metrics, employee performance, and resource usage. Accessible at `grafana.apex.unstuck-path.com`. | | **Prometheus** | latest | `apex-prometheus` | 9090 | ✅ Production | Maintenance | Time-series metrics collection and storage. Scrapes container metrics, resource usage, and custom application metrics. Powers Grafana dashboards and alerting rules. | | **Loki** | latest | `apex-loki` | 3100 | ✅ Production | Maintenance | Log aggregation system. Collects, indexes, and stores logs from all containers. Integrated with Grafana for log exploration and correlation with metrics. | | **Promtail** | latest | `apex-promtail` | — | ✅ Production | Maintenance | Log shipping agent. Tails container logs and forwards them to Loki. Configured to label logs by container name for easy filtering. | | **Langfuse** | v2 | `apex-langfuse` | 3000 | ✅ Production | Maintenance | LLM observability platform. Traces all LLM calls through LiteLLM, providing cost tracking, latency analysis, token usage breakdown, and quality evaluation. Accessible at `langfuse.apex.unstuck-path.com`. | ### 3.5 Security | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **Vaultwarden** | latest | `apex-vaultwarden` | 80 | ✅ Production | Maintenance | Self-hosted Bitwarden-compatible password manager. Stores all APEX OS credentials, API keys, and secrets. Accessible at `vaultwarden.apex.unstuck-path.com`. Admin token secured in Phase 1. | | **Docker Socket Proxy** | latest | `apex-socket-proxy` | 2375 | ✅ Production | Maintenance | TCP proxy for Docker socket access. Restricts Docker API operations to read-only: CONTAINERS, NETWORKS, SERVICES, TASKS. Prevents unauthorized container management from services that need limited Docker visibility. | ### 3.6 Automation & Communication | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **n8n** | latest | `apex-n8n` | 5678 | ✅ Production | Maintenance | Visual workflow automation platform. Hosts critical workflows: Telegram Command Center (Human CEO ↔ CEO Agent), Task Handler (task processing), Task Status Watcher (blocked task detection). Accessible at `n8n.apex.unstuck-path.com`. | | **Telegram Bot** | — | Via n8n webhook | — | ✅ Production | Maintenance | Communication interface for Human CEO. Bot: `@JimmysalesBot`. Webhook connected to n8n for message processing. Supports commands, approvals, and status queries. | **n8n Workflow Registry:** | Workflow | Purpose | Trigger | |----------|---------|---------| | Telegram Command Center | Routes Human CEO messages to CEO Agent | Telegram webhook | | Task Handler | Processes task creation and assignment | Internal trigger | | Task Status Watcher | Detects blocked/failed tasks and alerts | Scheduled (polling) | ### 3.7 Management | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **Dockge** | latest | `apex-dockge` | 5001 | ✅ Production | Maintenance | Docker Compose management UI. Provides visual management of Docker Compose stacks. Read-write Docker socket access. Secured with authentication in Phase 3. Accessible at `dockge.apex.unstuck-path.com`. | ### 3.8 Custom Services | Tool | Version | Container Name | Port(s) | Status | Lifecycle | Purpose | |------|---------|---------------|---------|--------|-----------|---------| | **APEX Status API** | 1.1 | `apex-status-api` | 3100 | ✅ Production | Maintenance | Custom-built health monitoring service. Provides `/health` endpoint with aggregated status of all APEX OS containers. Used by auto-recovery script (cron, every 5 min) and Grafana dashboards. | --- ## 4. Evaluation Criteria Every tool considered for APEX OS is evaluated against these criteria: | Criterion | Weight | Description | |-----------|--------|-------------| | **Open Source** | High | Open-source strongly preferred. Proprietary only with explicit justification. (Constitution: Open Source First Policy) | | **Docker Compatible** | Required | Must run in a Docker container via docker-compose. No host-level installations. (Constitution: Law 3) | | **Active Maintenance** | High | Must have meaningful commits within the last 6 months. Abandoned projects are not accepted. | | **Security Track Record** | High | No major unpatched CVEs. Supports non-root execution. Supports read-only filesystem where applicable. | | **Resource Efficiency** | Medium | Must operate within APEX OS resource budget (see §12). Memory and CPU usage measured during sandbox testing. | | **Integration Capability** | Medium | Must integrate with existing stack (Docker networks, Traefik labels, PostgreSQL, Redis as applicable). | | **Documentation Quality** | Medium | Must have clear installation, configuration, and API documentation. | | **Community Size** | Low | Larger communities provide better support and faster bug fixes, but niche tools with excellent quality are acceptable. | ### Evaluation Scoring | Score | Meaning | |-------|---------| | 5 | Exceeds all criteria — ideal fit | | 4 | Meets all criteria — good fit | | 3 | Meets most criteria — acceptable with caveats | | 2 | Meets minimum criteria — significant compromises | | 1 | Fails critical criteria — not recommended | **Minimum score for production adoption:** 3 (with documented caveats for any criteria scored below 3) --- ## 5. Certification Process ``` ┌─────────────┐ │ 1. RESEARCH │ Research alternatives (minimum 3) │ │ Document in research report format ├─────────────┤ │ 2. EVALUATE │ Score against evaluation criteria │ │ Compare alternatives in matrix ├─────────────┤ │ 3. SANDBOX │ Deploy in isolated Docker network │ │ Test core functionality ├─────────────┤ │ 4. BENCHMARK │ Measure resource usage (CPU, RAM, disk) │ │ Test under load (if applicable) ├─────────────┤ │ 5. SECURITY │ Review container permissions │ │ Check for CVEs │ │ Verify credential handling ├─────────────┤ │ 6. DOCUMENT │ Write evaluation report │ │ Include recommendation ├─────────────┤ │ 7. APPROVE │ Engineer (#1) technical approval │ │ Human CEO final approval (via Telegram) ├─────────────┤ │ 8. DEPLOY │ Add to docker-compose.yml │ │ Configure Traefik labels │ │ Add to this registry │ │ Add monitoring (Grafana/Prometheus) └─────────────┘ ``` ### Certification Report Template ```markdown # Tool Certification: [Tool Name] **Date:** [date] **Evaluator:** [Employee Name] (#[number]) **Category:** [Infrastructure/AI-ML/Development/etc.] ## Alternatives Evaluated 1. [Alternative A] — Score: X/5 2. [Alternative B] — Score: X/5 3. [Recommended Tool] — Score: X/5 ## Evaluation Matrix | Criterion | Alt A | Alt B | Recommended | |-----------|-------|-------|-------------| | Open Source | Y/N | Y/N | Y/N | | Docker Compatible | Y/N | Y/N | Y/N | | [etc.] | | | | ## Sandbox Test Results - Deployment: [success/issues] - Functionality: [verified features] - Stability: [24h test results] ## Resource Usage | Metric | Idle | Under Load | |--------|------|------------| | CPU | X% | X% | | Memory | X MB | X MB | | Disk | X MB | X MB | ## Security Review - [ ] No privileged mode - [ ] No root user (where possible) - [ ] Credential handling reviewed - [ ] CVE check passed ## Recommendation [Approve/Reject with reasoning] ``` --- ## 6. Lifecycle Stages Every tool in APEX OS passes through defined lifecycle stages: ``` Discovery → Evaluation → Sandbox → Testing → Staging → Production → Maintenance → Deprecation → Retirement ``` | Stage | Description | Duration | Exit Criteria | |-------|-------------|----------|---------------| | **Discovery** | Tool identified as potential solution | 1-2 days | Research report completed | | **Evaluation** | Scored against criteria, alternatives compared | 1-3 days | Evaluation matrix completed | | **Sandbox** | Deployed in isolated Docker network | 1-3 days | Core functionality verified | | **Testing** | Integration tested with existing stack | 1-3 days | All integrations working | | **Staging** | Running alongside production (shadow mode) | 1-7 days | 24h+ stability verified | | **Production** | Live, serving real workloads | Ongoing | Monitoring configured | | **Maintenance** | Regular updates, monitoring, optimization | Ongoing | Remains healthy and useful | | **Deprecation** | Replacement identified, migration planned | 1-4 weeks | Data migration complete | | **Retirement** | Removed from docker-compose, volumes cleaned | 1 day | Registry updated, docs updated | --- ## 7. Security Review Requirements Every tool must pass a security review before production deployment: ### 7.1 Container Security Checklist - [ ] **No `--privileged` flag** unless absolutely necessary (with documented justification) - [ ] **Non-root user** inside container (where the tool supports it) - [ ] **Read-only filesystem** (`:ro`) for mounts where possible - [ ] **No direct Docker socket access** — use Docker Socket Proxy if needed - [ ] **Network isolation** — tool on `apex_apex-net` network only - [ ] **No unnecessary ports exposed** to host - [ ] **Health check defined** in docker-compose ### 7.2 Credential Security - [ ] Credentials passed via environment variables (not command-line arguments) - [ ] No default passwords remaining - [ ] Credentials stored in Vaultwarden - [ ] Credential rotation plan documented ### 7.3 CVE Review - [ ] Check for known CVEs in the tool and its dependencies - [ ] Verify the tool's security advisory process - [ ] Ensure timely patching is feasible --- ## 8. Sandbox Testing Protocol ### 8.1 Sandbox Environment - Isolated Docker network: `apex-sandbox` - No access to production data or services - Separate PostgreSQL database (if needed) - Resource-limited (CPU and memory caps) ### 8.2 Test Duration - **Minimum:** 24 hours of continuous operation - **Recommended:** 72 hours for critical services - Monitoring for memory leaks, crash loops, and resource creep ### 8.3 Test Checklist - [ ] Container starts successfully - [ ] Health check endpoint responds - [ ] Core functionality works as documented - [ ] Integration with relevant APEX OS services verified - [ ] Resource usage within budget (see §12) - [ ] Logs are structured and meaningful - [ ] Graceful shutdown (responds to SIGTERM) - [ ] Recovery after container restart --- ## 9. Promotion Process To promote a tool from sandbox to production: 1. **Sandbox tests pass** — All checklist items verified 2. **Documentation complete** — Entry prepared for this registry 3. **Monitoring configured** — Grafana dashboard or Prometheus metrics 4. **Engineer (#1) approval** — Technical sign-off 5. **Human CEO approval** — Final approval via Telegram (Constitution Law 6) 6. **Production deployment** — Added to `docker-compose.yml` with proper labels 7. **Registry updated** — This document updated with new tool entry 8. **Team notified** — CEO Agent informed for task assignment updates --- ## 10. Retirement Process When a tool is no longer needed or has been replaced: 1. **Identify replacement** — Document what replaces this tool (or why it's no longer needed) 2. **Migrate data** — Transfer any data to replacement tool or archive 3. **Update integrations** — Reroute any dependencies to replacement 4. **Remove from docker-compose** — Stop and remove the container 5. **Clean up volumes** — Remove Docker volumes (after confirming backup) 6. **Update documentation** — Mark as retired in this registry 7. **Update monitoring** — Remove Grafana panels and Prometheus targets 8. **Log decision** — Record retirement in `engineer_decisions` --- ## 11. Update Strategy ### 11.1 Version Pinning - All tools **pin versions** in `docker-compose.yml` where possible - Use specific tags (e.g., `postgres:16.3`) rather than `latest` for critical services - `latest` tag acceptable for rapidly-evolving tools with good backward compatibility (e.g., Grafana, n8n) ### 11.2 Update Process 1. **Check release notes** — Review what changed in the new version 2. **Test in sandbox** — Pull new version in isolated environment 3. **Backup current state** — `cp docker-compose.yml docker-compose.yml.backup.*` 4. **Update docker-compose** — Change version tag 5. **Pull and restart** — `docker-compose pull [service] && docker-compose up -d [service]` 6. **Monitor for 15 minutes** — Watch logs and metrics for anomalies 7. **Rollback if needed** — Restore backup and previous image 8. **Log update** — Record in `engineer_decisions` ### 11.3 Update Frequency | Category | Update Cadence | Rationale | |----------|---------------|-----------| | Security patches | Immediate (within 24h) | Security is paramount | | Bug fixes | Weekly review | Stability improvements | | Feature updates | Monthly review | New capabilities when stable | | Major versions | Quarterly review | Thorough testing required | --- ## 12. Resource Budget ### 12.1 Current VPS Specifications - **Provider:** Hostinger - **IP:** 62.72.3.145 - **Resources:** Shared VPS (specific specs TBD in audit) ### 12.2 Resource Guidelines | Category | Guideline | |----------|-----------| | New tool idle memory | < 256 MB preferred, < 512 MB acceptable | | New tool idle CPU | < 5% preferred | | Total container count | Currently 20 — evaluate need before adding more | | Disk usage per tool | < 1 GB for application data (excluding logs) | ### 12.3 Resource Monitoring - Prometheus tracks per-container CPU, memory, and disk I/O - Grafana Executive Dashboard visualizes resource trends - Alerts configured for resource threshold breaches --- ## 13. Integration Map ``` ┌──────────────────────────────────────────────────────────────┐ │ INTERNET │ │ │ │ │ ┌──────▼──────┐ │ │ │ TRAEFIK │ SSL/Routing │ │ │ :80/:443 │ │ │ └──────┬──────┘ │ │ │ │ │ ┌────────────┼────────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Gitea │ │ Grafana │ │ n8n │ ...etc │ │ │ :3000 │ │ :3000 │ │ :5678 │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ┌──────▼────────────▼────────────▼──────┐ │ │ │ apex_apex-net (Docker) │ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ │ │PostgreSQL │ │ Redis │ │ │ │ │ │ :5432 │ │ :6379 │ │ │ │ │ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ │ │ LiteLLM │──│ Ollama │ │ │ │ │ │ :4000 │ │ :11434 │ │ │ │ │ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Letta │ │ Langfuse │ │ │ │ │ │ :8283 │ │ :3000 │ │ │ │ │ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ ┌──────────────┐ ┌───────────────┐ │ │ │ │ │ Vaultwarden │ │ Socket Proxy │ │ │ │ │ │ :80 │ │ :2375 │ │ │ │ │ └──────────────┘ └───────────────┘ │ │ │ └────────────────────────────────────────┘ │ │ │ │ External APIs: │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │OpenRouter │ │ Telegram │ │Let's │ │ │ │(LLM API) │ │ Bot API │ │Encrypt │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` --- ## 14. Change History | Date | Version | Author | Changes | |------|---------|--------|---------| | Phase 2 | 0.1 | Engineer (#1) | Initial registry — LiteLLM, Ollama added | | Phase 3 | 0.5 | Engineer (#1) | Added Gitea, Code-Server. Development tools category. | | Phase 4 | 0.8 | Engineer (#1) | Added mem0 (PostgreSQL + pgvector). Knowledge layer tools. | | Phase 5 | 1.0 | Engineer (#1) | Added Letta, auto-recovery. Full AI platform documented. | | Phase 5.5 | 1.5 | Engineer (#1) | Added Grafana, Prometheus, Loki, Promtail, Langfuse. Monitoring stack complete. Certification process formalized. | | Phase 7 | 2.0 | Engineer (#1) | Added n8n, Telegram Bot, APEX Status API. Full registry with lifecycle stages, security review, sandbox protocol, integration map. 20 containers documented. | --- > **This registry is the single source of truth for all tools in APEX OS. Before adopting, updating, or retiring any tool, consult this document and follow the defined processes.** *Cross-references: [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md) · [APEX_CONSTITUTION.md](APEX_CONSTITUTION.md) · [COMPANY_STRUCTURE.md](COMPANY_STRUCTURE.md)*