Build on LYDOS Agent OS
109 agents, 245 Q-engines, 128+ routers, 162 MCP tools. Internal alpha running on lydos.ailydian.com. This reference documents the real subsystems and extension points.
Subsystem layers
Every layer that processes a request from client to infrastructure.
Monolith vs Distributed
Choose the mode that matches your deployment target. Both run the same agent and engine code.
Monolith
DefaultLYDOS_MODE=monolithSingle Python process handles all routing, agent execution, and LLM calls. SQLite WAL for task queue and state. No external services required.
Advantages
- Zero-dependency startup (only .env required)
- All 29 modules and 109 agents available immediately
- Full LYD CLI and MCP server included
- Suitable for development and single-user production
Constraints
- Agent scheduler capped at 10 concurrent tasks
- No worker horizontal scaling
- SQLite not suitable for multi-user production load
Distributed
AlphaLYDOS_MODE=distributedControl-plane node handles API and task routing. Worker nodes pull tasks from message queue and execute agents in parallel. Relational database + cache layer for durable state.
Advantages
- Horizontal worker scaling (container compose --scale lydos-worker=N)
- Durable task queue via message queue with at-least-once delivery
- Relational database for multi-user state and audit trails
- Cache layer for low-latency cache (Q194 Persistent State)
Constraints
- Requires container runtime + Compose
- Message queue cluster is single-node (no TLS) in alpha
- Higher startup complexity
How data moves through LYDOS
Every communication channel documented with the actual implementation.
All REST API calls. Async request handling with retry logic in the http_client module (circuit breaker, exponential backoff).
Real-time agent status, health score stream, task updates. Pub/sub channels via websocket_hub. Connect at wss://lydos.ailydian.com/api/q62/dashboard/ws.
Priority queue with retry and dead-letter support via task_queue module. Distributed mode uses NATS JetStream streams for at-least-once delivery.
162 MCP tools exposed to Claude Code, Cursor, Windsurf, or any MCP client. Launch via: ~/.ailydos-venv/bin/python3 core/infrastructure/mcp_server.py --transport stdio
Speech-to-text via multi_stt_engine. Activated via ./lyd listen N or POST /api/voice/transcribe. Requires microphone access and PRIMARY_API_KEY.
In-process RPC between agents with circuit breaker and deadlock detection. Q29 Agent Hub delegates tasks using FC/ReAct/Plan-Execute/CoT strategies.
Q163 Distributed Mesh provides 5 load-balancing strategies and distributed state sync. Single-node in alpha — multi-node consensus not yet enabled.
29 active modules
Modules are health-monitored at GET /api/health. Overall score: 94/100 in the latest alpha run.
kernel_loader, config_manager, error_handler, self_healing_engine
agent_manager, harika_agent, harika_supreme, harika_ultra_team
primary_api, llm_router, primary_full_client, bilingual_client, analysis_api
rate_limiter, http_client, circuit_breaker, db_pool, observability, agent_scheduler, task_queue, websocket_hub, multi_stt_engine, semantic_memory, security_hardening, cuda_agent
mcp_server (162 tools), nim_llm_client
python_dependencies (7/7 checked)
245 Q-Series engines
Each engine registers its own FastAPI router under /api/q{N}/* in server.py.
Q25–Q40Plugins, DAG workflows, session intel, GEO-SEO, agent hub, skill library, CTI, bug bounty, hooks, research, visual automation
Q41–Q59TTS (23 languages), eval loop, adaptive LLM routing, code evolution, goal execution, MCP gateway, code graph, critic, benchmark, swarm, multimodal, meta-engine
Q60–Q71Git worktree isolation, CI/CD bridge, WS dashboard, multi-user JWT, hardware OBD-II, governance, context optimizer, reliability cert, cost intelligence, federated learning, marketplace
Q72–Q100Specialized agents: social, email, browser automation, file, calendar, finance, IoT, healthcare, legal, education, and more
Q101–Q1408 categories: Language/Platform, IDE, Cloud, Data/AI, Security, Industry, Communication, Embedded
Q141–Q158Production audit, anomaly detection, root cause, auto-remediation, WAF/threat intel, SEO sentinels (7 types), user command interpreter, DB/CDN/e-commerce sentinels, compliance, performance, cross-site intel, orchestrator, AI chat assistant, user consciousness, autonomous engineering
Q159–Q178Universal LLM gateway, visual canvas, A2A bridge, MCP mega-gateway (30 MCP servers), distributed mesh, self-modification engine, cognitive planner, temporal reasoning, predictive tasks, cross-project intel, AIOS kernel, self-verification, emergent behavior, marketplace, NL OS, agent dreaming, auto-docs, SDK gen, demo sandbox, telemetry
Q179–Q192Autonomous consciousness: global workspace, metacognition, adaptive memory, attention schema, reputation, proactive tasks, permission matrix, ADR records, active inference, safety policy guard, DAG re-planner, motivation state, transparent execution, skill transfer
Q193–Q213Security fortress, persistent state (relational+cache+embedded), horizontal scaling (container orchestrator), API docs, feedback analytics, skill factory, schema drift monitor, cross-platform adapter, user workspace, compliance engine, agent economy, Google OAuth, user settings, multimodal workspace, real-time collab, memory graph, smart caching, workflow templates, API versioning, batch processing, health aggregator
Q214–Q220Advanced intelligence: neuro-symbolic reasoning, causal discovery, counterfactual simulation, embodied agent bridge, meta-learning optimizer, emergent communication, quantum-inspired optimizer — registered, not fully production-validated
Q222–Q232Durable state recovery, event-triggered automation, token-accurate context condenser, agent tournament ranked scoring, SOC 2 compliance, public MCP registry (20 built-in), visual workflow designer, multi-region edge deploy, auto-approval engine, code agent engine, external API bridge
Q240–Q248Wireless recon (WiFi/OUI/HMAC audit), edge device manager, token optimizer, sandbox hardening, GitHub OAuth (Device Flow + PKCE), magic link & OTP auth, test synthesis, PR lifecycle management, migration engine with dry-run and rollback
Full endpoint listing with request/response schemas:
API Reference →From clone to running
Real commands that work against the actual codebase.
Local development workflow — start, verify, test
| 1 | # 1. Start the server (in one terminal) |
| 2 | source ~/.ailydos-venv/bin/activate |
| 3 | cd ~/Masaüstü/AILYDIAN-AGENT-OS |
| 4 | python3 server.py |
| 5 | |
| 6 | # 2. Verify it's alive (in another terminal) |
| 7 | curl -s https://lydos.ailydian.com/api/health | python3 -m json.tool |
| 8 | |
| 9 | # 3. Run the frontend (optional) |
| 10 | cd web && npm run dev |
| 11 | # → http://localhost:3001 |
| 12 | |
| 13 | # 4. Use the LYD CLI |
| 14 | ./lyd status # system overview |
| 15 | ./lyd hedef # goal hierarchy |
| 16 | ./lyd tasks # today's tasks |
| 17 | |
| 18 | # 5. Run tests |
| 19 | source ~/.ailydos-venv/bin/activate |
| 20 | python3 -m pytest tests/test_core.py tests/test_agent_manager.py -v |
| 21 | |
| 22 | # 6. Test a specific Q-engine |
| 23 | curl -s https://lydos.ailydian.com/api/q26/workflow/status | python3 -m json.tool |
| 24 | curl -s https://lydos.ailydian.com/api/q43/routing/status | python3 -m json.tool |
| 25 | |
| 26 | # 7. Test MCP server standalone |
| 27 | ~/.ailydos-venv/bin/python3 core/infrastructure/mcp_server.py --transport stdio |
How to extend LYDOS
Six ways to add capabilities without modifying core infrastructure.
New Q-engine
core/engines/q_new_engine.py + core/routes/q_new_route.pyAdd a FastAPI router in core/routes/, implement the engine in core/engines/, and register the router in server.py with app.include_router(). The health system picks it up automatically if the module defines a get_health() function.
YAML agent
config/agents.yamlAppend an agent definition (name, description, system_prompt, tools, category) to config/agents.yaml. The agent_manager loads all YAML agents at startup — no code change required.
Python agent
core/agents/my_agent.pyImplement a class that follows the BaseAgent interface (run, health methods). Register it in core/agents/__init__.py. agent_manager will include it in the total agent count.
MCP tool
core/infrastructure/mcp_server.pyAdd a new @mcp_tool decorated function. The tool becomes immediately available to AI IDEs, Cursor, and any other MCP client after restarting the MCP server process.
AI IDE skill
~/.claude/skills/ or config/skills/Create a .md skill file following the LYDOS skill format. The skill becomes available via the /skill-name command in AI IDE sessions. 87 skills are currently bundled.
Hook
hooks/LYDOS uses 11 hooks: session-start.sh (auto-start server, health cache write), post-compact.sh (goal/health injection), pre-tool-use, and others. Add custom logic here for session lifecycle events.
162 MCP tools
Expose all LYDOS capabilities to AI IDEs, Cursor, Windsurf, and any MCP-compatible client.
.mcp.json configuration
| // Place in project root or ~/.config/claude/mcp.json |
| { |
| "mcpServers": { |
| "lydos": { |
| "command": "~/.ailydos-venv/bin/python3", |
| "args": [ |
| "core/infrastructure/mcp_server.py", |
| "--transport", |
| "stdio" |
| ] |
| } |
| } |
| } |
Tool categories
run_agent, list_agents, get_agent_statusprimary_chat, llm_chat, stream_responseq26_workflow, q34_research, q43_routing, ...store_memory, search_memory, consolidatesystem_health, module_statussubmit_task, get_task, cancel_tasksecurity_scan, validate_inputWhat is and is not available
Honest account of the current alpha state for developers integrating with LYDOS.
Available now
- Full REST API on https://lydos.ailydian.com
- 109 agents (13 Python + 99 YAML)
- Q25–Q248 beta-stage engines
- 162 MCP tools via STDIO transport
- 4 LLM provider chain (Primary Provider)
- LYD CLI (./lyd) for system management
- WebSocket real-time monitoring (Q62)
- Distributed cluster via container-compose.alpha.yml
- Next.js frontend at localhost:3001
Not yet available
- Python SDK (in development)
- TypeScript SDK (in development)
- Hosted API (lydos.ailydian.com)
- Public repository (currently private)
- Q214–Q220 fully production-validated
- Multi-node message queue cluster with TLS
- SOC 2 certification (roadmap Phase 4)
- Public MCP registry (Q227) — alpha only
- VS Code extension on Marketplace
Detailed constraint list with workarounds:
Internal Alpha Guide →Dig deeper
Getting Started
Clone, install, start, and verify the server in 5 minutes.
Internal Alpha
Cluster bring-up, feature flags, known constraints, troubleshooting.
Architecture
29-module table, directory structure, health monitoring.
API Reference
Full REST endpoint docs with request/response schemas.
Q-Engine Catalogue
Q25–Q248 with endpoint prefixes and descriptions.
MCP Setup
Connect AI IDE, Cursor, or any MCP client.
LLM Providers
Primary, Bilingual, Analysis, Cloud Provider docs.
Agents Guide
Build Python and YAML agents, lifecycle management.
Start building on LYDOS
Server is at https://lydos.ailydian.com. Clone the private repo, activate the venv, and run python3 server.py.