Metadata-Version: 2.4
Name: opendevops
Version: 0.1.1
Summary: Autonomous DevOps agent: policy-gated, budget-capped, audit-chained operations on Kubernetes, GitHub, cloud CLIs, and SSH
Project-URL: Homepage, https://github.com/skundu42/opendevops
Project-URL: Repository, https://github.com/skundu42/opendevops
Project-URL: Issues, https://github.com/skundu42/opendevops/issues
Author: Sandipan Kundu
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,automation,devops,kubernetes,langchain,langgraph,llm,sre
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: <4.0,>=3.11
Requires-Dist: deepagents==0.6.12
Requires-Dist: langchain-anthropic<2,>=1.4.7
Requires-Dist: langchain==1.3.14
Requires-Dist: langgraph==1.2.9
Requires-Dist: pydantic-settings>=2.6
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.15
Provides-Extra: checkpoint
Requires-Dist: aiosqlite; extra == 'checkpoint'
Requires-Dist: langgraph-checkpoint-sqlite; extra == 'checkpoint'
Provides-Extra: dev
Requires-Dist: agentevals==0.0.9; extra == 'dev'
Requires-Dist: fakeredis<3,>=2.31; extra == 'dev'
Requires-Dist: langgraph-cli[inmem]==0.4.31; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: server
Requires-Dist: authlib<2,>=1.6; extra == 'server'
Requires-Dist: fastapi; extra == 'server'
Requires-Dist: httpx<1,>=0.27; extra == 'server'
Requires-Dist: langgraph-sdk<0.5,>=0.4; extra == 'server'
Requires-Dist: opentelemetry-api<2,>=1.30; extra == 'server'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30; extra == 'server'
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == 'server'
Requires-Dist: prometheus-client; extra == 'server'
Requires-Dist: redis>=5; extra == 'server'
Requires-Dist: sse-starlette; extra == 'server'
Provides-Extra: slack
Requires-Dist: aiohttp; extra == 'slack'
Requires-Dist: apscheduler<4,>=3.10; extra == 'slack'
Requires-Dist: slack-bolt==1.30.0; extra == 'slack'
Provides-Extra: ssh
Requires-Dist: asyncssh==2.24.0; extra == 'ssh'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/opendevops-mark.png" width="148" alt="opendevops logo">
</p>

<h1 align="center">opendevops</h1>

<p align="center">
  <strong>An autonomous DevOps agent with a smaller blast radius than its prompt.</strong>
</p>

<p align="center">
  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.
</p>

<p align="center">
  <a href="https://github.com/skundu42/opendevops/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/skundu42/opendevops/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/skundu42/opendevops/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/skundu42/opendevops?display_name=tag&sort=semver"></a>
  <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-28516b.svg"></a>
  <img alt="Python 3.11 and 3.12" src="https://img.shields.io/badge/python-3.11%20%7C%203.12-28a6a1.svg">
  <img alt="Project status: beta" src="https://img.shields.io/badge/status-beta-f0643b.svg">
</p>

---

## What is opendevops?

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.

```text
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)
```

### Capabilities

| 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 |
| 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.

## Operations dashboard

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.

<p align="center">
  <img src="docs/assets/dashboard.png" alt="Authenticated opendevops operations dashboard showing run activity, policy events, costs, audit integrity, and recent runs">
</p>

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.

```yaml
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]
```

```sh
docker compose up -d
open http://localhost:8123/dashboard
```

For production, register the callback exactly, terminate TLS before Caddy, use Redis sessions, and
keep requester and approver group membership operationally separate. See
[deployment](guides/deployment.md#operator-dashboard).

## Guarded dangerous actions

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.

```sh
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 grants
```

The control plane is an additional gate: a grant never overrides a policy deny, credential scope,
target allowlist, or dry-run requirement. AWS, GCP, and Azure policy packs remain read-only until
reviewed deployment commands and distinct rw credentials are added. Production Kubernetes
execution also requires `targets.kubernetes.kubeconfig_rw_by_environment.prod`; the legacy
`kubeconfig_rw` field is accepted only as a staging fallback.

## Why the execution model is different

```mermaid
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](guides/security-model.md) before connecting real infrastructure.

## Quick start

### Prerequisites

- Python 3.11 or 3.12
- [`uv`](https://docs.astral.sh/uv/)
- `kubectl` and access to a cluster where you can create the agent ServiceAccount
- an Anthropic API key
- optional provider CLIs only for integrations you enable

### Install and configure

```sh
# Install the prebuilt universal wheel; no repository clone or frontend build is needed.
uv tool install \
  'opendevops[checkpoint,ssh] @ https://github.com/skundu42/opendevops/releases/download/v0.1.1/opendevops-0.1.1-py3-none-any.whl'

mkdir opendevops-workspace
opendevops init opendevops-workspace
cd opendevops-workspace
cp .env.example .env
# Set ANTHROPIC_API_KEY in .env.

# 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 chat
```

The 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.

Continue with the [step-by-step getting-started guide](guides/getting-started.md).

## Configuration

Configuration is strict Pydantic over three files:

| File | Purpose |
|---|---|
| [`config/config.yaml`](config/config.yaml) | targets, credential variable names, execution, interfaces and service settings |
| [`config/models.yaml`](config/models.yaml) | agent model aliases and cache-aware pricing |
| [`config/budgets.yaml`](config/budgets.yaml) | per-run profiles, daily stop-losses and counter backend |
| [`config/policy/`](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](guides/configuration.md).

## Service mode

The included Compose stack runs the LangGraph Server, Postgres, Redis, Caddy, Vector, Prometheus,
Grafana, and the authenticated dashboard:

```sh
curl -fLO \
  https://github.com/skundu42/opendevops/releases/download/v0.1.1/opendevops-deploy-0.1.1.tar.gz
tar -xzf opendevops-deploy-0.1.1.tar.gz
cd opendevops-0.1.1
cp .env.example .env
# Fill every required blank in .env.

docker compose config -q
docker compose pull
docker compose up -d
```

The release bundle is pinned to `ghcr.io/skundu42/opendevops:0.1.1`; published images support
`linux/amd64` and `linux/arm64`. Neither Node.js nor an application source build is required. The
image intentionally contains the application runtime rather than every cloud vendor CLI; install
only the `kubectl`, `helm`, `gh`, `aws`, `gcloud`, or `az` binaries for policy families you enable
in a derived runtime image or credential-isolated executor. A missing binary fails closed.

Security-sensitive Compose credentials have no default values. Caddy is the only ingress; server
APIs and metrics require `GATEWAY_TOKEN`, native webhook routes retain their HMAC/bearer
authentication, and `/dashboard/*` uses the application session described above.

> [!WARNING]
> 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](guides/deployment.md) for TLS, shared counters, audit shipping, alerts, backups,
quota planning, and go-live gates.

## CLI

| 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 |

## Documentation

| Guide | Contents |
|---|---|
| [Getting started](guides/getting-started.md) | first installation and live session |
| [Architecture](guides/architecture.md) | graph, middleware, gateways, execution and data flow |
| [Configuration](guides/configuration.md) | every supported setting |
| [Policy](guides/policy.md) | rule schema, packs, precedence and extension |
| [Security model](guides/security-model.md) | trust boundaries, failure modes and residual risk |
| [Budgets](guides/budgets.md) | call limits, timeouts, pricing and USD stop-losses |
| [Audit](guides/audit.md) | event schema, verification, shipping and authenticity |
| [Interfaces](guides/interfaces.md) | CLI, dashboard, HTTP, webhooks, Slack and scheduler |
| [Deployment](guides/deployment.md) | service stack, monitoring and production gates |
| [Development](guides/development.md) | tests, conventions and extension points |
| [Upgrade notes](docs/UPGRADE.md) | dependency and migration guidance |
| [Release process](RELEASING.md) | versioning, artifacts, signing and PyPI trusted publishing |

## Development

```sh
npm ci
npm run frontend:check
npm run frontend:build

uv sync --extra checkpoint --extra server --extra slack --extra ssh --extra dev

uv run pytest -q
uv run ruff check .
uv run mypy src ops
uv lock --check
```

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the
[development guide](guides/development.md). Please report vulnerabilities privately according to
[SECURITY.md](SECURITY.md).

## License

Licensed under the [Apache License 2.0](LICENSE).
