RecourseOS — Consequence Verification for Autonomous Systems

Trust Boundary

Critical invariant: The agent does NOT receive raw Terraform, Kubernetes, shell, or cloud credentials. The agent receives ONLY gateway tools. The gateway owns execution credentials and applies policy, consequence evaluation, approval checks, and audit logging before any mutation is executed.

This is the single most important security property of the gateway architecture. Unlike advisory mode where agents can bypass RecourseOS, the enforcement gateway is the only path to infrastructure mutations.

Quick Start

1. Start the gateway

recourse gateway serve -e prod

2. Verify configuration

recourse gateway doctor -e prod

3. Configure your agent

Add to Claude Desktop, Cursor, or any MCP client:

json

{
  "mcpServers": {
    "recourse-gateway": {
      "command": "npx",
      "args": ["-y", "-p", "recourse-cli@latest", "recourse", "gateway", "serve", "-e", "prod"]
    }
  }
}

Agent Setup

claude mcp add recourse-gateway --transport stdio -- npx -y recourse-cli@latest gateway serve -e prod

Or add to .mcp.json in your project.

Gateway Tools

The gateway exposes 14 tools to agents. These are the only tools agents can use to interact with infrastructure.

Terraform

Tool	Purpose	Gate Behavior
`gateway_terraform_plan`	Create evaluated plan	Returns plan_id
`gateway_terraform_apply`	Apply by plan_id	Requires valid plan_id + approval
`gateway_terraform_destroy`	Request destruction	Blocks in prod, escalates elsewhere

Kubernetes (Read-Only)

Tool	Purpose	Gate Behavior
`gateway_kubectl_get`	Get resources	Always allowed
`gateway_kubectl_logs`	Read pod logs	Always allowed
`gateway_kubectl_describe`	Describe resources	Always allowed

Kubernetes (Mutations)

Tool	Purpose	Gate Behavior
`gateway_kubectl_apply`	Apply manifest	Escalates for protected namespaces
`gateway_kubectl_delete`	Delete resources	Always escalates
`gateway_kubectl_scale`	Scale workloads	Escalates for scale-to-zero
`gateway_kubectl_exec`	Exec into container	Always escalates

Shell

Tool	Purpose	Gate Behavior
`gateway_shell_exec`	Run shell command	Sandboxed with allow/block lists

Approval & Audit

Tool	Purpose	Gate Behavior
`gateway_request_approval`	Request human approval	Creates pending approval
`gateway_check_approval`	Check approval status	Returns status only
`gateway_get_plan`	Retrieve plan details	Read-only audit

Human Control Plane

Important: Agents can request approvals and check their status, but they can NEVER approve or reject. Those actions are human-only.

Agent-Callable (MCP)	Human-Only (Control Plane)
`gateway_request_approval`	approve
`gateway_check_approval`	reject
—	break_glass
—	policy_override

Human approvals happen through the dashboard, Slack, ServiceNow, or other configured approval providers — never through agent tools.

Plan-Bound Terraform

Terraform apply requires a valid plan_id from a prior plan evaluation. The gateway verifies:

1.Plan exists in the store
2.Plan has not expired (default: 1 hour TTL)
3.Plan hash matches (no drift since planning)
4.Workspace matches the original plan
5.Approval granted (if the plan decision was "escalate")

If any check fails, the apply is rejected. Agents cannot bypass these checks.

Shell Sandbox

Category	Behavior	Examples
Allowed	Execute immediately	`ls, cat, git status, kubectl get`
Escalate	Requires approval	`rm, aws, terraform apply, helm`
Block	Never execute	`curl\|bash, rm -rf /, sudo su`

Always Blocked

curl | sh
curl | bash
wget | sh
bash <(curl ...)
rm -rf /
rm -rf ~
sudo su
sudo -i
chmod 777
nc -e (reverse shell)

Policy Configuration

Create a policy.yaml for custom enforcement rules:

yaml

recourseos:
  version: '2.0'

  environments:
    dev:
      default_mutation: allow
      terraform_destroy: escalate
    staging:
      default_mutation: warn
      terraform_destroy: escalate
    prod:
      default_mutation: escalate
      terraform_destroy: block

  protected_namespaces:
    - kube-system
    - monitoring
    - production

  shell:
    always_block:
      - 'curl | sh'
      - 'rm -rf /'
      - 'sudo su'
    always_escalate:
      - 'aws'
      - 'terraform apply'

  plan_ttl_seconds: 3600
  approval_ttl_seconds: 86400

Start with custom policy: recourse gateway serve -e prod -p policy.yaml

Environment Policy

Environment	Default Mutation	Destroy	kubectl exec
dev	allow	escalate	escalate
staging	warn	escalate	escalate
prod	escalate	block	escalate

Gateway Doctor

Before deploying to production, verify your gateway configuration:

recourse gateway doctor -e prod

Runs 28 self-tests covering tool exposure, terraform enforcement, plan lifecycle, kubernetes gates, and shell sandbox patterns.

Full gateway doctor documentation →

Security Guarantees

Guarantee	Mechanism
No credential leakage	Agent never sees raw credentials
Plan integrity	Apply only works with verified plan hash
Temporal bounds	Plans expire (1h), approvals expire (24h)
Audit completeness	All attempts recorded, including blocks
Approval isolation	Agents cannot approve their own requests
Policy enforcement	Gateway policy cannot be modified by agents