Dockfra: Generic Docker Infrastructure Manager with AI Agents

Manage any Docker Compose project with an interactive web wizard, auto-discovery, SSH-isolated AI agents, ticket-driven workflows, and autonomous orchestration.

Key Features

Zero-config auto-discovery — scans for docker-compose.yml, parses ${VAR:-default} env vars (55+ auto-detected)
Web setup wizard — chat-based UI with inline forms, smart suggestions, ⚡ auto-detect, 10 languages
SSH role isolation — 4 agent roles (Developer, Manager, Monitor, Autopilot) in isolated containers
5 dev engines — Built-in LLM, Aider, Claude Code, OpenCode, MCP SSH Manager
Ticket-driven pipeline — create → assign → implement (AI) → review → deploy → close
Device emulation — devices/ stack emulates production machines (RPi3 with SSH + HTTP/HTTPS)
CLI + TUI — 14 commands: dockfra cli test, engines, doctor, tickets, pipeline, dev-logs...
Works with any project — just point at a directory with docker-compose.yml

Who is Dockfra for?

🧑‍💻 Solo developer / freelancer

Problem: You have a Docker Compose project with a database, backend, frontend, traefik — 50+ env vars scattered across files. Every setup is manual, every crash means an hour of digging through logs.

Dockfra: Run dockfra --root . and get a web wizard that auto-discovers your services, asks about missing variables, suggests values, and launches everything in one click. When a container crashes — you get a diagnosis and a "fix" button.

Docker Compose is the engine. Dockfra is the cockpit with auto-suggestions.

👥 Small team (2–5 people)

Problem: Developer commits, but who deploys? Who checks logs? Who decides what's next? Everything goes through Slack, tickets in Jira live their own life, disconnected from code.

Dockfra: Four SSH-isolated roles (Developer, Manager, Monitor, Autopilot) — each in a separate container with its own permissions. Manager creates a ticket, Developer implements it with AI assistance (Aider, Claude Code, or others), Monitor deploys and verifies. Everything in one system, tickets synced with GitHub Issues / Jira.

Ticket → code → deploy is one pipeline, not three tools.

🤖 AI coding enthusiast

Problem: You want to use AI for coding, but: which tool to pick? How to configure it in a container? What if one doesn't work — switch manually?

Dockfra: Five AI engines (Built-in LLM, Aider, Claude Code, OpenCode, MCP SSH) auto-detected. The system tests which one works and picks the best. You can switch engines per ticket. AI codes in an isolated SSH container — no access to your host.

Claude Code is a hammer. Dockfra is a workshop — gives you a hammer, screwdriver, saw, and tells you which tool to use.

⚙️ DevOps / sysadmin

Problem: You set up infrastructure for clients — every project has a different set of containers, different variables, different ports. Documentation exists, but it's still manual work every time.

Dockfra: Zero-config auto-discovery — scans docker-compose.yml, extracts all ${VAR:-default}, groups, validates, offers preflight checks before launch. CLI with 14 commands: dockfra cli doctor diagnoses problems, test runs a full self-test, engines checks AI status. Works with any project — just a directory with docker-compose.yml.

Coolify is a PaaS (Heroku-like). Kamal is a deploy pipeline. Dockfra is ongoing management — from config, through AI-assisted coding, to device deployment.

📡 IoT / embedded developer

Problem: You want to test deployment on a Raspberry Pi, but you don't have a physical device handy, or you don't want to risk production.

Dockfra: The devices/ stack emulates RPi3 — SSH for deployment, HTTP server with health endpoint, VNC for visual inspection. Deploy from the Monitor role, automatic verification.

TL;DR

Audience	Value
Solo dev	"No manual config — the wizard does it for me"
Small team	"Ticket → AI codes → review → deploy in one place"
AI coding fan	"5 AI engines, automatic selection, SSH isolation"
DevOps	"Any Docker Compose project, zero-config, CLI with diagnostics"
IoT dev	"Device emulation without physical hardware"

📖 Documentation

Document	Description
Getting Started	Quickstart for any Docker project
Architecture	System design, engines, pipeline, CLI (10 modules)
Configuration	`dockfra.yaml`, ENV_SCHEMA, auto-discovery layers
SSH Roles	Role separation, commands, isolation
Wizard API	REST + WebSocket API reference
Comparisons	vs Kamal, Coolify, Portainer, CrewAI, OpenDevin
TODO	Current roadmap and task status
Changelog	Release history

Quick Start

Any Docker Compose Project

pip install -e .
cd /path/to/your-project       # must have subdirs with docker-compose.yml
dockfra --root .               # Web wizard at http://localhost:5050

Full Dockfra Infrastructure

git clone https://github.com/wronai/dockfra.git && cd dockfra
make wizard                    # Web wizard at http://localhost:5050
# or manually:
make init && make up           # Generate keys, start all stacks

CLI (no browser needed)

dockfra cli                    # Interactive REPL
dockfra cli test               # Full system self-test
dockfra cli doctor             # Diagnose & fix issues
dockfra cli tickets            # List tickets
dockfra cli engines            # LLM engine status
dockfra cli dev-health         # SSH developer health
dockfra cli --tui              # Three-panel curses TUI

Architecture

┌────────────────────────────────────────────────────────────────────┐
│ LOCAL HOST — dockfra-shared network bridge                         │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  management/                        app/ (auto-cloned)             │
│  ┌──────────────────────────┐      ┌────────────────────────────┐  │
│  │ • ssh-manager   :2202    │      │ • ssh-developer :2200      │  │
│  │   └ 12 scripts (tickets, │      │   └ Aider, Claude Code,    │  │
│  │     config, planning)    │◄────►│     OpenCode, Built-in LLM │  │
│  │ • ssh-autopilot :2203    │shared│ • frontend, backend        │  │
│  │   └ 4 scripts (pilot-*)  │ net  │ • db, redis, traefik       │  │
│  │ • ssh-monitor   :2201    │      └────────────────────────────┘  │
│  │   └ 8 scripts (deploy,   │                                      │
│  │     verify, analyze)     │      devices/ (production emulation) │
│  │ • desktop (VNC :6081)    │      ┌────────────────────────────┐  │
│  └──────────────────────────┘      │ • ssh-rpi3  :2224 (SSH)    │  │
│                                    │ • web-rpi3  :8090 (HTTP)   │  │
│  dockfra/ (Python package)         │ • vnc-rpi3  :6082 (VNC)    │  │
│  ┌───────────────────────────┐     │   /health, /api/status     │  │
│  │ core.py  — foundation     │     └────────────────────────────┘  │
│  │ app.py   — web + 20 APIs  │                                     │
│  │ steps.py — wizard flow    │      shared/                        │
│  │ engines.py — 5 dev engines│     ┌────────────────────────────┐  │
│  │ pipeline.py — ticket chain│     │ Dockerfile.ssh-base        │  │
│  │ cli.py  — 14 CLI commands │     │ lib/ (llm, tickets, logger)│  │
│  │ fixes.py — auto-repair    │     └────────────────────────────┘  │
│  └───────────────────────────┘                                     │
└────────────────────────────────────────────────────────────────────┘

Dev Engines

Engine	Type	Status	Description
Built-in LLM	OpenRouter API	✅	`llm_client.py` — fast, configurable, multi-model
Aider	CLI pair-programmer	✅	Auto-commits, codebase mapping, iterative fixing
Claude Code	Anthropic CLI	✅ ★	Agentic, native SSH, file editing + git
OpenCode	Go CLI agent	⚙️	Open-source, chat-style coding, offline mode
MCP SSH Manager	SSH orchestration	⚙️	37 SSH tools for AI-driven server management

Engine selection is automatic (first working) or manual via wizard/CLI. See engines.py.

Auto-Discovery System

STACKS = {"app": Path, "management": Path, "devices": Path}  # scan for docker-compose.yml
ENV_SCHEMA = _build_env_schema()  # 62 entries (8 core + 54 from compose files)

Rebranding

DOCKFRA_PREFIX=myapp dockfra --root .
# → myapp-shared (network), myapp-ssh-base (image), myapp-traefik (container)

Role Separation

Capability	Manager	Autopilot	Developer	Monitor
Create/manage tickets	✓	✓	—	—
SSH to all roles	✓	✓	—	—
Configure LLM per role	✓	—	—	—
Edit code / git push	—	—	✓	—
AI pair programming (5 engines)	—	—	✓	—
Deploy to devices	—	—	—	✓
Health monitoring	—	—	—	✓
Autonomous orchestration	—	✓	—	—

Each role runs in an isolated Docker container with SSH keys and independent LLM config. See SSH Roles.

CLI

14 commands available via dockfra cli <command>:

Command	Description
`test`	🧪 Full system self-test (containers, engines, APIs)
`doctor`	🩺 Diagnose issues and suggest fixes
`status`	📊 Container health overview
`tickets`	🎫 List all tickets with status/priority
`diff <T-XXXX>`	📄 Show ticket diff and commits
`pipeline <T-XXXX>`	🔄 Run full pipeline for ticket
`engines`	🤖 Show LLM engine status
`dev-health`	🔧 Developer container health check
`dev-logs [N]`	📋 SSH developer container logs
`logs [N]`	📋 Last N wizard log lines
`launch [stack]`	🚀 Launch stacks
`ask <text>`	🧠 Free-text LLM query
`action <val>`	▶️ Raw wizard action value
`--tui`	Three-panel curses TUI (chat + processes + logs)

Setup Wizard

Chat-based web UI at http://localhost:5050 with three panels:

Panel	Features
💬 Chat	Step-by-step config, inline forms, AI chat, ⚡ auto-detect, smart chips
⚙️ Stats	Container status, engine health, developer logs, ticket diffs
📋 Logs	Streaming Docker Compose output, error analysis

Key capabilities:

Auto-discover stacks and env vars from docker-compose.yml
5 dev engines — select engine per ticket, auto-fallback
Ticket pipeline — create → implement (AI) → review → deploy
Docker error analysis → interactive fix buttons
Git clone integration — clone app repo on first launch
Dashboard at /dashboard — real-time container status + decision log

See Wizard API for REST + WebSocket reference.

Ticket-Driven Workflow

Manager creates ticket ──► /shared/tickets/T-0001.json ──► Developer picks up
      │                            ▲                              │
      │ ticket-push                │ ticket-pull                  │ AI implement
      ▼                            │                              ▼
  GitHub Issues ◄──────────────────┘                     Review → Deploy
                                                           │
                                                  ssh-monitor → devices/
                                                  (HTTP/SSH verify)

Device Emulation (`devices/`)

The devices/ stack emulates production machines for testing deployments:

Service	Port	Description
`ssh-rpi3`	`:2224`	SSH deploy channel (deployer user)
`web-rpi3`	`:8090`	Nginx HTTP server (`/health`, `/api/status`)
`vnc-rpi3`	`:6082`	Web VNC access

# Test from ssh-monitor:
curl http://web-rpi3:80/health              # → {"status":"ok","device":"rpi3"}
ssh deployer@ssh-rpi3 -p 2222 'ls /home/deployer/apps'

Customization with `dockfra.yaml`

lang: pl
env:
  POSTGRES_PASSWORD:
    label: "Database Password"
    group: Database
    type: password
  MY_CUSTOM_VAR:
    label: "Custom Setting"
    group: Custom
    default: "value"

See Configuration for full reference.

Makefile Reference

Target	Description
`make wizard`	Start web wizard at `:5050`
`make init` / `make up` / `make down`	Initialize / start / stop stacks
`make restart`	Restart wizard + stacks
`make clone-app`	Clone app repo from `GIT_REPO_URL`
`make ssh-developer` / `ssh-manager` / `ssh-monitor` / `ssh-autopilot`	SSH into roles
`make setup-all`	GitHub keys + LLM + dev tools
`make test`	Test suite (36 tests)
`make ps`	Show running containers

Project Structure

dockfra/
├── dockfra/                    # ══ PYTHON PACKAGE (10 modules) ══
│   ├── core.py                 # Foundation: config, discovery, Flask, Docker utils
│   ├── app.py                  # Web server, 20+ API routes, SocketIO
│   ├── steps.py                # Wizard step functions
│   ├── engines.py              # 5 dev engines (Aider, Claude Code, OpenCode, etc.)
│   ├── pipeline.py             # Ticket implementation pipeline
│   ├── tickets.py              # Ticket CRUD + GitHub sync
│   ├── fixes.py                # Auto-repair functions
│   ├── discover.py             # SSH role & command discovery
│   ├── cli.py                  # CLI with 14 commands + TUI
│   ├── llm_client.py           # OpenRouter LLM client
│   ├── templates/              # index.html, dashboard.html
│   └── static/                 # wizard.js, wizard.css
├── shared/                     # ══ SHARED RESOURCES ══
│   ├── Dockerfile.ssh-base     # Universal SSH base image
│   ├── lib/                    # llm_client.py, ticket_system.py, logger.py
│   └── tickets/                # T-0001.json, T-0002.json, ...
├── management/                 # ══ MANAGEMENT STACK ══
│   ├── docker-compose.yml      # ssh-manager, ssh-autopilot, ssh-monitor, desktop
│   ├── ssh-manager/            # 12 scripts (tickets, config, planning)
│   ├── ssh-autopilot/          # 4 scripts (pilot-run, pilot-plan, pilot-status)
│   └── ssh-monitor/            # 8 scripts (deploy-*, verify, analyze-logs)
├── app/                        # ══ APP STACK (auto-cloned from GIT_REPO_URL) ══
│   ├── docker-compose.yml      # Your app services + ssh-developer
│   └── ssh-developer/          # AI dev workspace (Aider, Claude Code, OpenCode)
├── devices/                    # ══ DEVICES STACK (production emulation) ══
│   ├── docker-compose.yml      # ssh-rpi3, web-rpi3 (nginx), vnc-rpi3
│   ├── ssh-rpi3/               # SSH deploy channel with helper scripts
│   ├── web-rpi3/               # Nginx config + health endpoints
│   └── vnc-rpi3/               # VNC access to device
├── docs/                       # Architecture, Getting Started, Config, API
├── comparisons/                # vs Kamal, Coolify, Portainer, CrewAI, OpenDevin
├── tests/                      # 36 tests (E2E + unit)
├── scripts/                    # Setup helpers (GitHub keys, LLM, dev tools)
├── Makefile                    # Operational targets
└── CHANGELOG.md / TODO.md

Comparisons

See comparisons/ for detailed analysis:

vs	Category	Key difference
Kamal	Deployment	Dockfra = ongoing AI manager; Kamal = deploy pipeline
Coolify	Self-hosted PaaS	Dockfra = Docker Compose native; Coolify = Heroku-like
Portainer	Docker GUI	Dockfra = project-specific + AI agents; Portainer = infra-wide
CrewAI/AutoGen	Multi-agent AI	Dockfra = real OS containers; CrewAI = Python processes
OpenDevin/Aider	AI dev agents	Dockfra = full DevOps lifecycle; OpenDevin = code only

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com

Name		Name	Last commit message	Last commit date
Latest commit History 116 Commits
.github/workflows		.github/workflows
TODO		TODO
comparisons		comparisons
devices		devices
dockfra		dockfra
docs		docs
management		management
scripts		scripts
shared		shared
tests		tests
.gitignore		.gitignore
.nojekyll		.nojekyll
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
VERSION		VERSION
dockfra.yaml		dockfra.yaml
goal.yaml		goal.yaml
img.png		img.png
img_1.png		img_1.png
index.html		index.html
init.sh		init.sh
project.functions.toon		project.functions.toon
project.sh		project.sh
project.toon-schema.json		project.toon-schema.json
test_parse.py		test_parse.py

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Dockfra: Generic Docker Infrastructure Manager with AI Agents

Key Features

Who is Dockfra for?

🧑‍💻 Solo developer / freelancer

👥 Small team (2–5 people)

🤖 AI coding enthusiast

⚙️ DevOps / sysadmin

📡 IoT / embedded developer

TL;DR

📖 Documentation

Quick Start

Any Docker Compose Project

Full Dockfra Infrastructure

CLI (no browser needed)

Architecture

Dev Engines

Auto-Discovery System

Rebranding

Role Separation

CLI

Setup Wizard

Key capabilities:

Ticket-Driven Workflow

Device Emulation (devices/)

Customization with dockfra.yaml

Makefile Reference

Project Structure

Comparisons

License

Author

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Device Emulation (`devices/`)

Customization with `dockfra.yaml`

Packages