apex-os-docs/TOOL_REGISTRY.md

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 · APEX_CONSTITUTION.md

---

Table of Contents

• 1. Purpose
• 2. Tool Categories
• 3. Current Tool Registry
  • 3.1 Infrastructure
  • 3.2 AI/ML Platform
  • 3.3 Development Tools
  • 3.4 Monitoring & Observability
  • 3.5 Security
  • 3.6 Automation & Communication
  • 3.7 Management
  • 3.8 Custom Services
• 4. Evaluation Criteria
• 5. Certification Process
• 6. Lifecycle Stages
• 7. Security Review Requirements
• 8. Sandbox Testing Protocol
• 9. Promotion Process
• 10. Retirement Process
• 11. Update Strategy
• 12. Resource Budget
• 13. Integration Map
• 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

# 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 · APEX_CONSTITUTION.md · COMPANY_STRUCTURE.md