How mittal122/helmsman works
Helmsman is an AI-assisted Kubernetes deployment platform with a deterministic deployment core and an advisory LLM layer. Developers submit an image, Git repository, Compose stack, or structured intake through the web console; the backend normalizes inputs and coordinates build, manifest generation, validation, scanning, deployment, and verification. Separate capabilities provide live progress, workload management, self-healing guidance, optional authentication, and durable event/audit history. Edges reflect shown imports and calls or README-documented flows; several feature modules are represented by their exact directories because their implementation was not sampled.
Main entry points: coordinator.py Deploy coordinator · main.py HTTP API · store.py History and audit store · static Web consoles
Components 24
Intake and API
- Web consoles
backend/static - HTTP API
backend/main.py - Structured intake
backend/intake.py - Compose parser
backend/tools/compose.py
Deployment lifecycle
- Deploy coordinator
backend/coordinator.py - Source builder
backend/tools/builder.py - Manifest rendering
backend/tools/manifests.py - Validation and scan
backend/tools - Deploy and verify
backend/tools/deploy.py - Deploy monitoring
backend/tools/monitor.py - Rollback
backend/tools/rollback.py
Advisory and recovery
- Advisory agents
backend/agents - LLM client
backend/agents/base.py - Failure diagnostics
backend/diagnostics.py
Cluster operations
- Cluster manager
backend/tools/cluster.py - Port forwarding
backend/tools/portforward.py
Identity and state
- Authentication and RBAC
backend/auth.py - Encrypted kubeconfigs
backend/kubeconfig_store.py - Event stream
backend/events.py - History and audit store
backend/store.py
Other components
- Developer
- Kubernetes cluster
- LLM provider
- PostgreSQL
Connections 24
- Developer → Web consoles: uses
README.md - Web consoles → HTTP API: submits requests
README.md - HTTP API → Deploy coordinator: dispatches deployment
backend/main.py - HTTP API → Structured intake: builds and ingests
backend/main.py - HTTP API → Compose parser: parses stacks
backend/main.py - Deploy coordinator → Source builder: builds source
backend/coordinator.py - Deploy coordinator → Manifest rendering: renders manifests
backend/coordinator.py - Deploy coordinator → Validation and scan: validates and scans
backend/coordinator.py - Deploy coordinator → Deploy and verify: deploys and verifies
backend/coordinator.py - Deploy coordinator → Deploy monitoring: checks health
backend/coordinator.py - Deploy coordinator → Rollback: rolls back
backend/coordinator.py - Deploy coordinator → Failure diagnostics: generates guidance
backend/coordinator.py - Deploy coordinator → Advisory agents: requests advice
backend/coordinator.py - Advisory agents → LLM client: calls
backend/agents/stack_reviewer.py - LLM client → LLM provider: requests completion
backend/agents/base.py - Deploy coordinator → Event stream: emits progress
backend/coordinator.py - Deploy coordinator → Kubernetes cluster: operates on
README.md - HTTP API → Cluster manager: serves management
backend/main.py - Cluster manager → Port forwarding: starts forwarding
backend/tools/cluster.py - HTTP API → Authentication and RBAC: enforces access
backend/main.py - Authentication and RBAC → History and audit store: reads user records
backend/auth.py - Deploy coordinator → Encrypted kubeconfigs: loads cluster config
backend/coordinator.py - Event stream → History and audit store: persists event history
README.md - History and audit store → PostgreSQL: uses when configured
README.md