An autonomous DevOps agent with a smaller blast radius than its prompt.
Investigate infrastructure, diagnose incidents, and perform tightly scoped operations through argv-only execution, least-privilege credentials, fail-closed policy, budget stop-losses, and structurally verifiable audit chains.
opendevops is an open-source operations agent built on LangGraph and LangChain deepagents. It can trace a CrashLoop, analyze CI failures, inspect cloud resources, verify drift, summarize noisy logs, and execute a deliberately narrow set of staging remediations.
The model never receives a shell. Every command is an argv: list[str] request that passes through
budget controls, a default-deny policy engine, a credential-selection boundary, output scrubbing,
and a per-run audit chain.
you › why is pod api-0 in namespace web crash-looping?
→ run_command kubectl -n web describe pod api-0
→ run_command kubectl -n web logs api-0 --previous --tail 200
The container was OOMKilled (exit 137). Its JVM heap is configured above the
container memory limit. Reduce the heap or raise the workload limit.
spent $0.0841 (run) / $0.34 (today)
| Area | Supported today | Boundary |
|---|---|---|
| Kubernetes | diagnostics, logs, events, Helm inspection, controlled apply/rollout/scale | production rw requires an active expiring grant, server dry-run, independent approval and rw kubeconfig |
| GitHub | CI diagnosis, run inspection, PR-based remediation | repository and API method/path allowlists |
| AWS | curated EC2, ECS, RDS, CloudFormation, S3, Lambda, CloudWatch and related reads | no cloud-resource deployment or IAM access |
| Google Cloud | curated Compute, GKE, Cloud SQL, Pub/Sub, Logging, Storage, Run and Functions reads | mutations and secret access denied |
| Azure | curated VM, AKS, ACR, networking, SQL, Cosmos DB, Monitor and resource reads | mutations and secret material denied |
| Models | Anthropic (default), OpenAI, Azure OpenAI, Google, Amazon Bedrock, OpenAI-compatible endpoints | non-Anthropic providers need an optional extra; every alias needs a pricing row |
| Remote hosts | structured, read-only SSH checks | pinned user, key, hosts and known_hosts |
| Interfaces | CLI, HTTP, Slack, scheduler, Alertmanager and GitHub webhooks | one shared gateway and safety core |
| Operations UI | identity-scoped agent chat, live runs, approvals, policy/cost/audit detail and capability grants | OIDC RBAC + CSRF; chat never exposes raw tool arguments, output, or credential values |
Important
This is not a general AWS, Google Cloud, or Azure deployment engine. Terraform, Pulumi, CloudFormation updates, Google Cloud Deploy, ARM/Bicep deployment, and unrestricted provider CLI mutations are not enabled.
- Python 3.11 or 3.12
uvkubectland access to a cluster where you can create the agent ServiceAccount- an API key for your configured model provider (Anthropic by default)
- optional provider CLIs only for integrations you enable
# Install the published package; no repository clone or frontend build is needed.
uv tool install "opendevops[checkpoint,ssh]==0.2.1"
mkdir opendevops-workspace
opendevops init opendevops-workspace
cd opendevops-workspace
cp .env.example .env
# Set ANTHROPIC_API_KEY in .env (default models.yaml aliases).
# Provision a read-only, secrets-denied Kubernetes identity.
kubectl apply -f ops/k8s/agent-view-rbac.yaml
ops/k8s/gen-kubeconfig.sh <your-context>
# Add <your-context> to targets.kubernetes.allowed_contexts in config/config.yaml.
opendevops config check
opendevops chatThe generated workspace deliberately has an empty Kubernetes context allowlist. config check
and every runtime entry point refuse to proceed until you make that deployment choice explicitly.
opendevops init also refuses to replace an existing workspace unless --force is explicit.
Default aliases use Anthropic. To point at OpenAI, Azure OpenAI, Google, Bedrock, or an
OpenAI-compatible endpoint, edit config/models.yaml (aliases, optional providers, and
pricing), install the matching extra (models-openai, models-google, models-bedrock, or
models for all three), and set the credential env named by that provider.
Continue with the step-by-step getting-started guide.
| Command | Purpose |
|---|---|
opendevops init [directory] |
scaffold config and Kubernetes bootstrap files from the wheel |
opendevops chat |
streaming REPL with environment, profile and principal selection |
opendevops config check |
validate runtime-critical configuration |
opendevops config grants |
list the control-plane revision and capability proposals |
opendevops config propose-grant |
propose a typed, expiring dangerous capability |
opendevops config approve-grant |
approve a proposal (requester separation in prod) |
opendevops config activate-grant / revoke-grant |
activate or immediately revoke a grant |
opendevops audit verify --dir <dir> |
strictly verify audit structure and completion |
opendevops audit verify --allow-incomplete |
diagnose structurally valid crashed/in-progress runs |
opendevops version |
print the installed version |
| Guide | Contents |
|---|---|
| Getting started | first installation and live session |
| Architecture | graph, middleware, gateways, execution and data flow |
| Configuration | every supported setting |
| Policy | rule schema, packs, precedence and extension |
| Security model | trust boundaries, failure modes and residual risk |
| Budgets | call limits, timeouts, pricing and USD stop-losses |
| Audit | event schema, verification, shipping and authenticity |
| Interfaces | CLI, dashboard, HTTP, webhooks, Slack and scheduler |
| Deployment | service stack, monitoring and production gates |
| Development | tests, conventions and extension points |
| Upgrade notes | dependency and migration guidance |
| Release process | versioning, artifacts, signing and PyPI trusted publishing |
The service-mode dashboard includes an authenticated command channel for asking the agent directly about connected infrastructure. Conversations are private to the exact OIDC issuer and subject; operator/admin turns stream over SSE, retain a bounded transcript, and use the same gateway, budgets, policy, capability grants, and approval path as every other interface. The chat shows assistant responses and sanitized lifecycle activity, never raw command arguments or tool output.
The rest of the dashboard merges verified audit chains with live gateway telemetry. It shows active runs, queues, workers, pending approvals, per-model timing and cost progression, policy decisions, tool timing, correlation IDs, spend, SLIs, and audit integrity. Operators can cancel runs; approvers can resolve interruptions; admins can activate or revoke typed capability grants.
Production authentication is generic OpenID Connect (Entra ID, Google Workspace, Okta, Keycloak,
or another standards-compliant issuer). Groups/roles map to viewer, operator, approver, and
admin. Browser cookies contain only an opaque random session handle; session state and OIDC
transactions are stored server-side, support immediate revocation, and expire within eight hours.
Every control action records the OIDC issuer and subject. Static-token login remains available only
as the explicit local-development mode.
server:
dashboard_auth_mode: oidc
dashboard_session_backend: redis
dashboard_session_redis_url: redis://redis:6379/2
dashboard_cookie_secure: true
dashboard_chat_enabled: true
dashboard_chat_retention_days: 30
dashboard_chat_max_message_chars: 8000
oidc:
issuer: https://id.example.com/realms/operations
client_id_env: OIDC_CLIENT_ID
client_secret_env: OIDC_CLIENT_SECRET
redirect_uri: https://ops.example.com/dashboard/oidc/callback
roles_claim: groups
role_mappings:
viewer: [devops-readers]
operator: [devops-operators]
approver: [change-approvers]
admin: [devops-admins]docker compose up -d
open http://localhost:8123/dashboardFor production, register the callback exactly, terminate TLS before Caddy, use Redis sessions, and keep requester and approver group membership operationally separate. See deployment.
Dangerous capabilities are versioned state, not free-form dashboard YAML. An operator proposes a specific environment, capability, explicit target set, reason, lifetime, execution count, per-run/repeat limit, failure threshold, cooldown, and mandatory dry-run. An approver approves it; an admin activates it. Production rejects requester self-approval, and the executor atomically consumes the grant before each rw action.
opendevops config propose-grant \
--environment prod \
--capability kubernetes_deploy \
--target kind-prod/web \
--reason "Deploy reviewed release 2026.07.26"
opendevops config approve-grant <proposal-id> --actor change-approver
opendevops config activate-grant <proposal-id> --actor platform-admin
opendevops config grantsThe control plane is an additional gate: a grant never overrides a policy deny, credential scope,
target allowlist, or dry-run requirement. Curated AWS / Google Cloud / Azure write packs
(aws-write / gcloud-write / az-write) unlock scale/rollout-class ops only when distinct
credential_env_rw identities are configured; IAM, secret access, destroy, and provider-wide
deployment remain denied. Production Kubernetes execution also requires
targets.kubernetes.kubeconfig_rw_by_environment.prod; the legacy kubeconfig_rw field is
accepted only as a staging fallback.
flowchart LR
I["CLI · API · Slack · Scheduler · Webhooks · OIDC dashboard chat"] --> G["AgentGateway"]
O["OIDC session + RBAC"] --> I
G --> B["Budgets and call limits"]
B --> P["Fail-closed policy"]
P -->|allow / rewrite| E["argv-only executor"]
P -->|escalate| H["Human decision"]
P -->|deny| D["Refusal"]
E --> C["One scoped credential"]
X["Expiring capability grant + loop limits"] --> P
H --> X
C --> T["Kubernetes · GitHub · Cloud CLIs · SSH"]
P --> A["Audit chain"]
E --> A
B --> A
A --> U["Authenticated dashboard"]
A --> W["WORM / SIEM sink"]
- No shell surface. Commands execute with
shell=False; interpreters and command-building utilities are denied. - Credentials are the hard boundary. The executor constructs a fresh environment and injects exactly one credential family for the winning rule and channel.
- Policy fails closed. Unknown tools, commands, flags, contexts, identities, and policy errors deny execution.
- Secrets stay out of argv. Standalone
{{secret:NAME}}declarations inject environment variables for env-aware programs and are removed before execution; embedded expansion is denied. - Outputs are scrubbed first. Known token forms and high-entropy strings are redacted before model context, virtual files, or audit excerpts.
- USD limits are stop-losses. Call, tool, recursion, and wall-clock limits are hard controls; cost is known after model calls and can overshoot by in-flight work.
- Audit claims are precise. Local SHA-256 chains prove structural consistency. Authenticity requires the independently protected WORM or INSERT-only sink used in production.
Read the full security model before connecting real infrastructure.
Configuration is strict Pydantic over three files:
| File | Purpose |
|---|---|
config/config.yaml |
targets, credential variable names, execution, interfaces and service settings |
config/models.yaml |
agent model aliases, optional providers, and cache-aware pricing |
config/budgets.yaml |
per-run profiles, daily stop-losses and counter backend |
config/policy/ |
base denies, environment overlays and capability packs |
Unknown keys fail validation. Missing credentials for an enabled policy family fail agent construction. Secret values belong in the process environment, never YAML.
See the complete configuration reference.
The included Compose stack runs the LangGraph Server, Postgres, Redis, Caddy, Vector, Prometheus, Grafana, and the authenticated dashboard:
curl -fLO \
https://github.com/skundu42/opendevops/releases/download/v0.2.1/opendevops-deploy-0.2.1.tar.gz
tar -xzf opendevops-deploy-0.2.1.tar.gz
cd opendevops-0.2.1
cp .env.example .env
# Fill every required blank in .env.
docker compose config -q
docker compose pull
docker compose up -dWarning
Never run the service stack on a Kubernetes cluster the agent itself manages. Use a dedicated operations VM or a separate operations cluster.
See deployment for TLS, shared counters, audit shipping, alerts, backups, quota planning, and go-live gates.
npm ci
npm run frontend:check
npm run frontend:build
uv sync --extra checkpoint --extra server --extra slack --extra ssh --extra models --extra dev
uv run pytest -q
uv run ruff check .
uv run mypy src ops
uv lock --checkContributions are welcome. Start with CONTRIBUTING.md and the development guide. Please report vulnerabilities privately according to SECURITY.md.
Licensed under the Apache License 2.0.