​
Services

SynapseX is organized as internal services behind the public API Gateway. Clients should call https://api.synapsex.ai/v1; direct service URLs are for local development and internal networking.

​
Core Services

ServicePortOwns
api-gateway8080Public /v1 API, auth forwarding, service routing
auth-service8001Login, register, token validation, API keys
agent-registry-service8002VM agent registration and heartbeats
policy-service8003Tool and environment policy decisions
audit-service8004Append-only audit events and exports
ai-ops-service8005Operational AI task runner and remediation flows
license-service8006License state and entitlement checks
vm-registry-service8007VM inventory and telemetry snapshots
incidents-service8008Incident records and AI analysis hooks
secrets-service8009Secret metadata and rotation operations
backup-service8011Backup jobs and restore records
patch-service8012Patch inventories and patch jobs
billing-service8014Stripe billing, usage, quotas, subscriptions
orchestrator-service8015Agent jobs and orchestration
llm-router-service8018Model routing and OpenAI-compatible chat completions

​
Platform Foundation Services

These services complete the platform foundation for SaaS, runtime operations, integrations, and product control-plane features.
ServicePortPublic routePurpose
tenant-service8019/v1/tenantsTenants, plans, limits, members, workspace scoping
event-bus-service8020/v1/eventsDurable event publishing, consumption, ack/nack, dead-letter state
workspace-service8021/v1/workspacesWorkspaces, generated artifacts, diffs, run outputs
webhook-service8022/v1/webhooksWebhook subscriptions, signed deliveries, retries, delivery history
update-service8023/v1/updatesVM agent/runtime releases, rollouts, update checks
model-registry-service8024/v1/model-registry/modelsModel catalog, capabilities, provider metadata, model health
observability-service8025/v1/telemetryTelemetry events, trace lookup, service summary
mcp-router-service8026/v1/mcp/route, /v1/mcp/plan, /v1/mcp/askIntent classification and intelligent selection across QCOS, SynapseX, integrations and search MCPs

​
Request Flow

Client / SDK / CLI / Chat / Desktop Console
  -> api.synapsex.ai/v1
  -> api-gateway
  -> auth-service for identity and API keys
  -> policy-service, tenant-service, billing-service for guardrails
  -> orchestrator-service, llm-router-service, workspace-service, MCP bridge
  -> mcp-router-service for intelligent MCP/tool selection
  -> event-bus-service, audit-service, observability-service for durable records

​
Local Compose

The root docker-compose.yml now includes the foundation services. For backend-only work, infra/docker/docker-compose.services.yml includes the same service set with SQLite-backed volumes. 
docker compose up -d postgres api-gateway tenant-service event-bus-service workspace-service webhook-service update-service model-registry-service observability-service mcp-router-service

​
Design Notes

  • Services are intentionally internal by default; the API Gateway is the public contract.
  • All new services support DATABASE_URL and default to local SQLite for development.
  • Production should replace SQLite with PostgreSQL and place services behind private networking.
  • Webhook delivery uses HMAC signatures through X-SynapseX-Signature.
  • Event bus is durable through SQL and can later be swapped to Azure Service Bus, NATS, RabbitMQ, Kafka, or Redis Streams without changing public gateway routes.