Agentic Infra

Kubernetes infrastructure operations powered by Codex CLI, native operational CLIs, and Skills.

中文

Philosophy

Agentic Infra does not implement another agent framework or wrap every command in a remote MCP tool. Codex is the agent runtime: it interprets intent, reads skills, plans work, invokes commands, and summarizes evidence.

• Codex is the only agent: the backend runs codex exec --json with event streaming and session resume.
• CLIs are the execution surface: use kubectl, helm, argocd, git, ssh, curl, and skill scripts.
• Skills are the capability layer: SKILL.md stores workflows and judgment, scripts/ stores deterministic operations, and references/ is loaded on demand.
• Change control is enforced at the runtime boundary: plan permits non-mutating work; apply requires explicit approved=true, scoped to the exact request.
• MCP is legacy-only: the old implementation lives under legacy/ and is absent from default dependencies, images, and startup.

Architecture

Portal / API Client
        │  SSE / JSON
        ▼
FastAPI Runtime ── SkillRegistry
        │              │
        │              └─ skills/*/SKILL.md
        ▼
 codex exec --json
        │
        ├─ kubectl / helm / argocd
        ├─ git / ssh / curl
        └─ skills/*/scripts/*

Built-in skills

• infra-deploy-guide: ArgoCD, VictoriaMetrics, VictoriaLogs, and kube-prometheus-stack
• k3s-ops: K3s installation, expansion, upgrades, backup, restore, and maintenance
• k8s-diagnostic: Pod, node, scheduling, resource-pressure, and probe diagnostics
• monitoring-ops: PromQL, alerts, health checks, and capacity planning
• logging-ops: kubectl logs, LogsQL, VictoriaLogs, and collectors
• middleware-ops: Helm operations for Redis, MySQL, Kafka, and PostgreSQL

Each turn selects at most MAX_MATCHED_SKILLS skills. Codex reads each matching SKILL.md completely, then loads references or runs scripts only when needed.

Quick start

Prerequisites: Python 3.12+, Codex CLI, and the task-specific CLIs such as kubectl, Helm, Argo CD CLI, or ssh.

cp .env.example .env
uv sync --extra dev
codex login
uv run agentic-infra

Endpoints:

• Portal: http://localhost:3000
• API docs: http://localhost:8000/docs
• Health: http://localhost:8000/health

Start the portal:

cd portal
npm install
npm run dev

API

Non-mutating planning or diagnosis:

curl -N http://localhost:8000/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"message":"Check the current cluster for unhealthy Pods","stream":true}'

SSE responses include a thread.started event with session_id. Send that value on a later request to resume the Codex session.

Mutations require explicit approval:

curl -N http://localhost:8000/api/runs \
  -H 'Content-Type: application/json' \
  -d '{
    "message":"Apply the reviewed vm-stack upgrade in the monitoring namespace",
    "mode":"apply",
    "approved":true,
    "stream":true
  }'

Apply requests without approved=true return HTTP 409. Plan uses a workspace-write sandbox by default because kubectl-style CLIs require network access; runtime instructions prohibit mutations. Set CODEX_PLAN_SANDBOX=read-only for strict offline filesystem planning. The runtime preserves the user's Codex authentication and provider configuration; this project registers no MCP servers and explicitly directs Codex to native CLIs.

The Portal cluster initialization wizard follows the same two-stage flow. It first generates the target context, diff evidence, execution steps, and rollback path in plan mode. Only after the user reviews the output and checks the explicit approval control does it resume that plan's session_id in apply mode. Any configuration change invalidates the old plan and approval.

Create a skill

skills/my-skill/
├── SKILL.md
├── scripts/       # optional deterministic, repeated, or fragile operations
└── references/    # optional thresholds, configuration, and detailed guidance

SKILL.md frontmatter contains only:

---
name: my-skill
description: Describe the capability and the user requests that should trigger it.
---

Call POST /api/skills/reload after adding a skill; no service restart is needed.

Containers

cd deploy
docker compose up --build

The runtime image installs and verifies Codex, kubectl, Helm, and Argo CD CLI. Compose mounts the workspace, ~/.codex, ~/.kube, and read-only ~/.ssh. Production deployments should use a dedicated service account, least-privilege RBAC, dedicated Codex credentials, and a controlled workspace instead of personal directories.

Verification

uv run ruff check .
uv run pytest
cd portal && npm run typecheck && npm run build

Migration

The Agno runtime has been removed. Previous MCP servers and configuration moved to legacy/ for migration reference only and are not supported by the default test or deployment path.