RecourseOS - Architecture Diagram

1 · Intent sources request

AI agent

Claude Code, Cursor, Codex-style agents, internal SRE bots, autonomous remediation agents.

"I need to change infrastructure."

Human operator

An engineer runs Terraform, shell, kubectl, AWS CLI, gcloud, or az commands locally.

recourse shell -- "aws rds delete..."

CI / PR workflow

GitHub Actions, GitLab, Jenkins, Atlantis, Spacelift, Azure DevOps, or Terraform Cloud-style pipelines.

terraform show -json tfplan > plan.json

2 · Client layer transport

MCP client

The agent runtime discovers tools and decides whether to call RecourseOS before acting.

recourse_evaluate_terraform | _shell | _mcp_call

CLI

Manual checks, debugging, local reports, shell wrapping.

CI adapter

Exit codes, PR comments, merge gates, artifact uploads.

Local / team UI

Shows recent reports, blocked actions, approval history, evidence, and explanations.

recourse ui

3 · RecourseOS gate

RecourseOS

The pre-action consequence layer for infrastructure agents.

MCP server

Front door for agents. Exposes tools with descriptions that teach the agent to call before destructive work.

npx recourse-cli mcp serve

Adapters

Terraform plan, shell command, MCP tool call, kubectl/cloud CLI patterns.

Consequence engine

Per-resource rules, cross-action pattern detection, classifier for unknowns.

✗ Block unrecoverable No verified recovery path or destructive command skips safety mechanisms.

! Review ambiguous Unknown resource semantics, weak evidence, or policy requires approval.

✓ Allow recoverable Reversible or verified recovery evidence exists.

4 · Tools + targets action

MCP tools

The actual tools the agent wanted to call: Terraform, cloud APIs, Kubernetes, GitHub, CI, runbooks.

create · update · delete · rotate · revoke · apply

Terraform

plan, show JSON, apply, destroy, workspace changes.

Shell / CLI

aws, gcloud, az, kubectl, rm, chmod, psql, scripts.

Cloud + production

AWS, GCP, Azure, Kubernetes, databases, buckets, secrets, IAM, networks, queues.

mutation happens here only after verdict

Read-only evidence

Optional enrichment: snapshots, backup retention, object lock, versioning, deletion windows, IAM dependencies.

describe/list/read only

Policy + approval

Local policy, team policy, human approval, exception tracking, audit history.

block | review | allow

Gateway mode: RecourseOS gates tool access.

This is the strongest architecture. The agent does not get direct access to dangerous infrastructure tools. It must call RecourseOS first, receive a consequence report, and only then receive permission to call the mutation tool.

Agent proposes action."Delete this database," "run terraform apply," or "call this MCP tool."

MCP client calls RecourseOS.The preflight tool description tells the agent this is required before destructive actions.

RecourseOS evaluates consequence.Adapters normalize the intent, evidence enriches the report, and policy decides block/review/allow.

Only safe or approved actions reach cloud tools.Unrecoverable actions are blocked before they mutate AWS, GCP, Azure, Kubernetes, or Terraform state.

Gateway mode is the product-grade version: RecourseOS is in the action path, not just beside it.

{
  "tool": "recourse_evaluate_terraform",
  "input": {
    "plan_json": "{ ... terraform show -json output ... }"
  },
  "result": {
    "decision": "block",
    "recoverability": "unrecoverable",
    "resource": "aws_db_instance.main",
    "reason": "skip_final_snapshot=true, backup_retention_period=0",
    "evidence": {
      "deletion_protection": false,
      "final_snapshot": false
    }
  }
}

// Available tools:
recourse_evaluate_terraform  // Terraform plan JSON
recourse_evaluate_shell      // Shell commands
recourse_evaluate_mcp_call   // MCP tool calls
recourse_supported_resources // List coverage