# kubeclaw

OpenClaw operator for Kubernetes.

## What it does

Kubeclaw runs Scobleclaw agents as Kubernetes workloads with security-first design — agents get only one tool (`template_workflow`) that instantiates pre-approved workflow templates. Every workflow invocation is judged against compliance/regulatory policy by a separate LLM model.

## Architecture

```
┌──────────────────────────────────────────────────┐
│  Agent (only 1 tool: template_workflow)          │
│  ┌────────────────────────────────────────────┐  │
│  │ template_workflow("search-memory", {q:"X"})│  │
│  └────────────────┬───────────────────────────┘  │
│                   │                              │
└───────────────────┼──────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────────┐
│  Judge (deepseek-v4-pro)                         │
│  Evaluates: template + params + compliance rules │
│  Returns: APPROVE / REJECT / ESCALATE-HUMAN      │
│                                                  │
│  Checks against:                                 │
│  ┌────────────┐  ┌───────────────────────────┐   │
│  │ Compliance  │  │ Regulatory Frameworks    │   │
│  │ Policy CRD  │  │ (SOC2, HIPAA, GDPR, etc) │   │
│  └────────────┘  └───────────────────────────┘   │
└──────────────────┬───────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────┐
│  Workflow Executor                                │
│  Runs approved workflow steps                     │
│  Each step logs to audit trail                    │
│  Structured output per template schema            │
└──────────────────────────────────────────────────┘
```

## CRDs

### Provider (cluster-scoped)
LLM provider config — API keys, base URLs, model lists with pricing.

### Channel (namespaced)
Platform bindings — Discord, Slack, Telegram — with bot token refs.

### AgentConfig (namespaced)
Reusable `agents.defaults.*` config templates — workspace, memory, heartbeat, skills, sandbox, tools.

### WorkflowTemplate (cluster-scoped)
Pre-approved workflow templates with defined steps, parameters, output schema, and compliance requirements. The *only* thing agents can invoke.

### CompliancePolicy (cluster-scoped)
Compliance/regulatory policies that the judge evaluates workflow invocations against. Supports SOC2, HIPAA, GDPR, or custom frameworks with per-rule severity and escalation paths.

### Agent (namespaced)
Single agent deployment — references Config, Providers, Channels, WorkflowTemplates, CompliancePolicies.

### AgentGroup (namespaced)
Multi-agent orchestration with shared configs and per-member overrides.

## Security Model

```
┌──────────────────────────────────────────────────────┐
│  Agent Attack Surface                                 │
│                                                        │
│  Available tools: [template_workflow]                  │
│  Not available: exec, write, web_search, sessions_*,   │
│                 forgejo_*, lean_experiment_*, cron       │
│                                                        │
│  Judge validates every workflow call against:           │
│  ├─ WorkflowTemplate spec (schema, sources, dests)      │
│  ├─ CompliancePolicy rules (Soc2/HIPAA/GDPR checks)    │
│  ├─ Agent-level whitelists (allowed templates, sources) │
│  └─ Regulatory framework system prompt                  │
└──────────────────────────────────────────────────────┘
```

## Quick Start

```bash
# Install CRDs
make install

# Run controller locally
make run

# Deploy to cluster
helm install kubeclaw ./charts/kubeclaw
```

## CRD Listing

| CRD | Scope | Purpose |
|---|---|---|
| Provider | Cluster | LLM provider configs |
| Channel | Namespaced | Platform channel bindings |
| AgentConfig | Namespaced | Reusable config templates |
| WorkflowTemplate | Cluster | Pre-approved workflow templates |
| CompliancePolicy | Cluster | Security/compliance evaluation rules |
| Agent | Namespaced | Single agent deployment |
| AgentGroup | Namespaced | Multi-agent orchestration |

## License

MIT