Overview

The harness lets Claude Code, OpenCode, GitHub Copilot, Cursor, Windsurf, Codex CLI, Gemini CLI, or any OpenAI/Anthropic-compatible model operate as a semi-autonomous DevOps engineer: troubleshooting Kubernetes, Docker, Linux, AWS, Terraform, Ansible, CI/CD and Git, working Jira tickets end to end, running incident response and producing evidence-backed reports.

It behaves like an engineering platform, not a chatbot. Every task follows a fixed lifecycle, every tool call passes through a policy engine, and the agent stops whenever an operation is unsafe, ambiguous, unavailable or requires human approval.

USER REQUEST → TASK UNDERSTANDING → CONTEXT DISCOVERY → INSPECTION → ROOT CAUSE ANALYSIS
             → PLAN → RISK ASSESSMENT → APPROVAL GATE → IMPLEMENTATION → VALIDATION
             → DOCUMENTATION → JIRA / PR UPDATE → FINAL REPORT

Key capabilities

Commands

Specialist agents: Kubernetes · Docker · Linux · Jira · Git/PR · CI/CD · AWS · Terraform · Ansible · Networking · Observability · Security · Incident Response · Documentation

🚀 Quick start

Five minutes, no credentials, no infrastructure.

git clone https://github.com/stwins60/devops-agent-harness.git
cd devops-agent-harness
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

devops-agent --mock "Why is my Kubernetes API deployment failing?"
devops-agent --mock --yes jira DEVOPS-382
devops-agent --mock --approve-all incident "production API is returning 503"
devops-agent --mock plan "upgrade our Kubernetes worker nodes"
devops-agent --mock fix DEVOPS-382 --dry-run
make test

FACT: Deployment production/api: 0/3 replicas ready, image registry.example.com/sample-app/api:1.4.2, revision 7.
FACT: Pod api-7c98d9b55c-abc12: phase Running, ready=False, restarts=12, waiting reason CrashLoopBackOff, last exit code 137 (Error).
FACT: Event Unhealthy (41x): Readiness probe failed: dial tcp 10.0.1.21:8000: connect: connection refused
FACT: Application log shows it listens on port 8080.
FACT: Container api: containerPorts=[8080], probes=readinessProbe->8000/healthz, livenessProbe->8000/healthz.

HYPOTHESIS (confirmed, confidence 95%):
Probe port mismatch: readinessProbe checks port 8000 but the container listens on 8080; kubelet kills/never readies the pod.

HYPOTHESIS (rejected, confidence 40%):
Container was killed with exit 137 (SIGKILL); possible OOM kill (limit 512Mi, usage 48Mi) or liveness-probe kill.

CONCLUSION: Confirmed - Probe port mismatch ... (confidence 95%)
RECOMMENDATION: Set readinessProbe port to 8080 in the deployment manifest.

Mock scenarios: --scenario probe-port-mismatch | oom | image-pull | pending | config-error | healthy | ci-failure | disk-full

Failure injection: --flag jira_unavailable | k8s_unreachable | aws_creds_expired | git_push_rejected | pr_create_fails | terraform_plan_fails | tool_timeout | rollback_fails | partial_deploy | permission_denied

📦 Installation for production

Requirements: Python 3.10+, git. Optional CLIs used when present: kubectl, docker, aws, terraform, ansible-playbook, trivy, semgrep, gitleaks, checkov. Missing tools degrade gracefully.

# 1. Install from PyPI into an isolated environment
pipx install devops-agent-harness
# or: pip install devops-agent-harness

# 2. Initialise the repository the agent should operate on
cd /path/to/your/service-repo
devops-agent init        # creates .agent/config.yaml, .agent/{memory,decisions,runbooks,...} and an AGENTS.md skeleton

# 3. Provide credentials through the environment only (never in config files)
export JIRA_URL=https://your-company.atlassian.net JIRA_EMAIL=you@company.com JIRA_API_TOKEN=...
export GITHUB_TOKEN=...              # or GITLAB_TOKEN + GITLAB_URL
export KUBECONFIG=~/.kube/config     # contexts are bound to environments in .agent/config.yaml
export AWS_PROFILE=readonly          # standard AWS credential chain

# 4. First run in read-only mode to confirm environment resolution
devops-agent --mode read-only "why is deployment api failing in production?"

A complete go-live checklist (read-only identities, environment bindings, hardening, upgrades) is in docs/production.md. Docker-based local development is described in docs/development.md.

⚙️ Configuration

.agent/config.yaml lives in the target repository. Full reference: examples/config.example.yaml.

mode: approval                 # read-only | plan | approval | autonomous
environment: dev               # declared; trusted bindings below can only make it stricter
provider: auto                 # auto | mock | none | openai | anthropic | claude-code | opencode | copilot | ollama
jira_url: https://your-company.atlassian.net
github_repo: your-org/service-repo
git_provider: github           # or gitlab (+ gitlab_project)
default_namespace: production
prometheus_url: http://prometheus.monitoring:9090

environments:                  # trusted identity -> environment; anything unbound == production
  production: { kube_contexts: [prod-eks], aws_accounts: ["123456789012"], namespaces: [production] }
  staging:    { kube_contexts: [staging-eks], namespaces: [staging] }
  dev:        { kube_contexts: [kind-dev, docker-desktop], namespaces: [dev, default] }

mcp_preapproved: [git_create_branch, git_add, git_commit, jira_add_comment]   # low-risk writes allowed over MCP
mcp_servers: []                # consume other MCP servers as governed tools

Environment variable overrides: DEVOPS_AGENT_MODE, DEVOPS_AGENT_ENV, DEVOPS_AGENT_PROVIDER, DEVOPS_AGENT_NAMESPACE, DEVOPS_AGENT_GITHUB_REPO, DEVOPS_AGENT_TASKS_DIR, DEVOPS_AGENT_NON_INTERACTIVE, DEVOPS_AGENT_MOCK.

🧩 Using it from your IDE or coding agent

There are two integration directions and you can use both.

The MCP server command is identical for every client:

devops-agent --project-root /path/to/repo --mode approval mcp-serve

Over MCP there is no terminal, so an operation that needs approval is refused with an explanatory error and the task stays resumable. Approve it from a terminal with devops-agent execute TASK-ID.

Ready-to-use configuration files for every client are in examples/ide/. Full details, prompts and troubleshooting: docs/integrations.md.

claude mcp add devops-agent --scope project -- devops-agent --project-root . --mode approval mcp-serve

{ "mcpServers": { "devops-agent": { "command": "devops-agent",
    "args": ["--project-root", ".", "--mode", "approval", "mcp-serve"] } } }

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "devops-agent": {
      "type": "local",
      "command": ["devops-agent", "--project-root", "/path/to/repo", "--mode", "approval", "mcp-serve"],
      "enabled": true
    }
  },
  "agent": {
    "devops": {
      "description": "DevOps engineer using the governed devops-agent tools",
      "mode": "primary",
      "prompt": "{file:/path/to/repo/AGENTS.md}",
      "tools": { "devops-agent*": true, "atlassian*": false, "github*": false, "gitlab*": false }
    }
  }
}

{ "servers": { "devops-agent": { "type": "stdio", "command": "devops-agent",
    "args": ["--project-root", "${workspaceFolder}", "--mode", "approval", "mcp-serve"] } } }

[mcp_servers.devops-agent]
command = "devops-agent"
args = ["--project-root", ".", "--mode", "approval", "mcp-serve"]

printf '%s\n%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | devops-agent --mock mcp-serve

🤖 Using it as a model-driven CLI

The rule-based specialists diagnose without any model. A model is consulted only when they cannot conclude, and its tool requests still pass through policy and approval.

devops-agent --provider anthropic   jira DEVOPS-382                 # ANTHROPIC_API_KEY
devops-agent --provider openai      incident "…"                    # OPENAI_API_KEY (+ OPENAI_BASE_URL for Azure / vLLM)
devops-agent --provider ollama      "why is my pod crashing?"       # local OpenAI-compatible server
devops-agent --provider claude-code plan "…"                        # claude CLI
devops-agent --provider opencode    "…"                             # opencode CLI
devops-agent --provider copilot     "…"                             # copilot CLI

Interactive approvals show the operation, environment, risk, expected impact and rollback, and accept y / n / skip / diff / plan / rollback. DESTROY-class and production operations require typing approve <tool>. --yes auto-approves non-explicit prompts, --approve-all is for demos only, and --non-interactive (CI) denies and pauses so the task can be resumed from a terminal.

🛡️ Safety model

Details: docs/security.md · docs/approvals.md · SECURITY.md

🏗️ Architecture

                    ┌──────────────────────────┐
                    │   USER · IDE · MCP CLIENT │
                    └─────────────┬────────────┘
                                  ▼
                    ┌──────────────────────────┐
                    │      AGENT HARNESS       │  agent/harness.py
                    └─────────────┬────────────┘
            ┌─────────────────────┼─────────────────────┐
            ▼                     ▼                     ▼
      Orchestrator          Policy Engine         Approval Engine
      (lifecycle)         (YAML, outside LLM)   (interactive · allowlist · auto)
            │
            ▼
      Specialist Agents
      kubernetes · docker · linux · jira · git · cicd · aws · terraform
      ansible · networking · observability · security · incident · documentation
            │
            ▼
      Tool Executor  →  policy → approval → tool → audit log + task state + rollback plan
            │
            ▼
      Tool Registry (115 tools)
      Native · CLI · REST · MCP · SDK backends, each with a real and a mock implementation

Extension points: add a Tool (package build_tools()), an Agent (Specialist subclass), a Policy (.agent/policy.yaml), a Runbook (YAML) or a Provider adapter without touching the orchestrator. See docs/architecture.md and CONTRIBUTING.md.

🔧 Operations

📚 Documentation

Roadmap