Architecture

System Architecture

Akmatori uses a secure 4-container architecture with network isolation to provide safe, scalable AI-powered incident automation.

Component Overview

Alert Sources
AlertmanagerZabbixPagerDutyGrafanaDatadog
↓
πŸ’¬Slack Bot
⟷
⚑API ContainerIncident managementSkill orchestrationWebSocket to Codex
⟷
πŸ—„οΈPostgreSQLIncidents, SkillsCredentials (encrypted)
WebSocket↓
↓
πŸ€–Codex WorkerRuns Codex CLI
NO database accessNO direct secrets
⟷MCP calls
πŸ”ŒMCP GatewayFetches credentialsSSH/Zabbix execution
↓
🧠OpenAI API

Security Design

ContainerDatabase AccessSecrets AccessExternal Network
APIβœ… Fullβœ… Allβœ… Slack
MCP Gatewayβœ… Read-onlyβœ… Tool credentialsβœ… SSH, APIs
Codex Worker❌ None❌ Noneβœ… OpenAI only
PostgreSQLN/AN/A❌ Internal only

Key Security Features

Credential isolation

Codex container never sees database credentials

Per-incident auth

OpenAI API key passed via WebSocket for each task

Network segmentation

Three isolated Docker networks

UID separation

API (UID 1000) and Codex (UID 1001) for file permission control

Docker Services

akmatori-apiDockerfile.api

Main Go backend: incident management, skill orchestration, WebSocket server for Codex Worker

frontend, api-internal
postgrespostgres:16-alpine

PostgreSQL database storing incidents, skills, tools, and encrypted credentials

api-internal
mcp-gatewaymcp-gateway

Model Context Protocol gateway: fetches credentials from DB, executes SSH/Zabbix operations

api-internal, codex-network
akmatori-codexDockerfile.codex

Codex Worker: runs OpenAI Codex CLI for AI-powered incident investigation (isolated, no DB access)

codex-network

Network Isolation

Akmatori uses three separate Docker networks to ensure security through isolation:

frontend

External access for the UI and API proxy

api-internal

API ↔ Database, MCP Gateway ↔ Database connections

codex-network

Isolated network for Codex Worker ↔ MCP Gateway

The Codex container has no direct database access. All tool operations flow through the MCP Gateway, which handles credential resolution at runtime.

How It Works

Akmatori uses OpenAI Codex CLI in an isolated container to execute AI-powered automation tasks. When an alert is received or a skill is triggered:

1

Alert Normalization

API container extracts key fields using source-specific adapters

2

Incident Creation

Records context, creates workspace with skill files and symlinks

3

Task Dispatch

API sends task + OpenAI credentials to Codex Worker via WebSocket

4

AI Execution

Codex Worker runs Codex CLI in the incident workspace

5

Tool Calls

When Codex needs SSH/Zabbix access, Python wrappers call MCP Gateway

6

Credential Fetch

MCP Gateway retrieves credentials from database and executes the operation

7

Result Streaming

Output streams back through WebSocket to API for real-time updates

8

Completion

Results posted to Slack (if configured) and incident status updated

This architecture ensures the AI agent never has direct access to sensitive credentials.