# kubeclaw

**OpenClaw operator for Kubernetes** — runs Scobleclaw AI agents as first-class Kubernetes workloads with CRDs, controller loops, and security-hardened operator patterns.

> **Status:** Project Kickoff — Architecture & Spec Draft  
> **Author:** @agent-cos  
> **Related:** scobleclaw#7 (Agent Judge architecture), scobleclaw#8 (this ticket)

---

## What It Does

Kubeclaw brings Scobleclaw's agentic engineering patterns into Kubernetes. Instead of running agents as ad-hoc processes, kubeclaw models them as declarative K8s resources that the operator reconciles into running pods with proper configuration, secrets, channels, and authorization gating.

### Key Design Decisions

1. **Security-first agent surface** — Agents get *one* tool: `template_workflow`. No raw exec, no arbitrary file writes, no open web access. Every action flows through the judge.
2. **Actor-Judge separation** — The task agent (e.g., `@engineering`) and the authorization judge (`@judge`) are separate LLM model instances. The judge validates every workflow template invocation against CompliancePolicy CRDs before execution proceeds.
3. **Declarative all the way** — Every agent, channel binding, workflow template, and compliance policy is a Kubernetes CRD. The controller reconciles desired state → running state.
4. **Pluggable providers** — LLM providers (OpenAI, Anthropic, Ollama, OpenClaw gateway) are cluster-scoped Provider CRDs with API key references.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Kubernetes Cluster                           │
│                                                                      │
│  ┌─────────────────┐    ┌─────────────────┐    ┌───────────────┐   │
│  │  Agent CRD       │    │  AgentGroup CRD  │    │  AgentConfig  │   │
│  │  (agent spec)    │    │  (orchestration) │    │  (templates)  │   │
│  └────────┬─────────┘    └────────┬─────────┘    └───────┬───────┘   │
│           │                       │                      │           │
│           ▼                       ▼                      ▼           │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                 kubeclaw Controller (Reconciler)              │   │
│  │                                                               │   │
│  │  1. Watch Agent/AgentGroup resources                          │   │
│  │  2. Reconcile → create/update/delete Agent Pods               │   │
│  │  3. Inject config, secrets, channel bindings                  │   │
│  │  4. Wire judge sidecar for template_workflow authorization    │   │
│  └─────────────────────────┬────────────────────────────────────┘   │
│                            │                                         │
│                            ▼                                         │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                     Agent Pod (3 containers)                  │   │
│  │                                                               │   │
│  │  ┌─────────────────────┐  ┌─────────────────────┐            │   │
│  │  │     Actor Agent     │  │  Judge Sidecar       │            │   │
│  │  │  (OpenClaw agent)   │──│  (deepseek-v4-pro)   │            │   │
│  │  │                     │  │  Validates workflow  │            │   │
│  │  │  Tool:              │  │  invocations against │            │   │
│  │  │  template_workflow  │  │  CompliancePolicy    │            │   │
│  │  └─────────────────────┘  └─────────────────────┘            │   │
│  │                                                               │   │
│  │  ┌────────────────────────────────────────────────────────┐  │   │
│  │  │             Workflow Executor Sidecar                   │  │   │
│  │  │  Runs approved workflow steps, logs to audit trail      │  │   │
│  │  │  Each step: structured input → structured output        │  │   │
│  │  └────────────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐    │
│  │ WorkflowTemplate  │  │ CompliancePolicy │  │  Provider CRD  │    │
│  │ CRD (cluster)     │  │ CRD (cluster)    │  │  (cluster)     │    │
│  └──────────────────┘  └──────────────────┘  └────────────────┘    │
│                                                                      │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐    │
│  │  Channel CRD     │  │  Secret (K8s)    │  │  ConfigMap     │    │
│  │  (namespaced)    │  │  (API keys)      │  │  (agent config)│    │
│  └──────────────────┘  └──────────────────┘  └────────────────┘    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

## CRD Reference

### Provider (cluster-scoped)

LLM provider configuration — API endpoints, model lists, pricing.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: Provider
metadata:
  name: openclaw-gateway
spec:
  type: openclaw  # openai | anthropic | ollama | openclaw
  baseURL: https://os.scoble.me/api
  apiKeyRef:
    name: openclaw-credentials
    key: api-key
  models:
    - name: deepseek-v4-flash:cloud
      contextWindow: 65536
      costPer1KInput: 0.0005
      costPer1KOutput: 0.0015
    - name: deepseek-v4-pro:cloud
      contextWindow: 128000
      costPer1KInput: 0.001
      costPer1KOutput: 0.003
  defaultModel: deepseek-v4-flash:cloud
```

### Channel (namespaced)

Platform binding — Discord, Slack, Telegram, etc.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: Channel
metadata:
  name: engineering-discord
  namespace: agents
spec:
  platform: discord
  botTokenRef:
    name: discord-bot-tokens
    key: engineering-bot
  guildID: "123456789"
  allowedChannels:
    - "agent-logs"
    - "engineering-chat"
```

### AgentConfig (namespaced)

Reusable agent configuration templates — workspace, memory, skills, sandbox, tools.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: AgentConfig
metadata:
  name: standard-engineering
  namespace: agents
spec:
  workspace:
    mountPath: /workspace
    size: 10Gi
  memory:
    enabled: true
    retentionDays: 90
  skills:
    - id: forgejo
      version: "1.0"
    - id: filesystem
      version: "1.0"
    - id: discord
      version: "1.0"
  sandbox:
    type: gvisor
    networkPolicy: internal-only
  resources:
    cpu: "2"
    memory: "4Gi"
    gpu: 0
```

### WorkflowTemplate (cluster-scoped)

Pre-approved workflow templates — the **only** thing agents can invoke. Each template defines input parameters, execution steps, output schema, and compliance requirements.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: WorkflowTemplate
metadata:
  name: search-memory
spec:
  description: Search agent memory for relevant context
  version: "1.0"
  parameters:
    - name: query
      type: string
      required: true
      description: Search query string
    - name: maxResults
      type: integer
      default: 10
      minimum: 1
      maximum: 50
  steps:
    - id: embed-query
      action: llm-embed
      input: "{{ .Params.query }}"
    - id: vector-search
      action: vector-db-query
      input: "{{ .Steps.embed-query.output }}"
      limit: "{{ .Params.maxResults }}"
    - id: format-results
      action: llm-complete
      input: "Format these memory results: {{ .Steps.vector-search.output }}"
  output:
    type: structured
    schema:
      results:
        type: array
        items:
          type: object
          properties:
            id: { type: string }
            content: { type: string }
            timestamp: { type: string }
            relevance: { type: number }
  compliance:
    requiredFrameworks: []
    dataClassification: internal
```

### CompliancePolicy (cluster-scoped)

Regulatory and security policies the judge evaluates workflow invocations against.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: CompliancePolicy
metadata:
  name: soc2-baseline
spec:
  framework: SOC2
  version: "2025"
  rules:
    - id: data-access-scope
      severity: critical
      description: Agent must not access data outside its designated scope
      eval: check_data_access_scope(request)
      onViolation: REJECT
    - id: pii-handling
      severity: high
      description: PII must not be written to external channels
      eval: check_pii_in_output(request)
      onViolation: REJECT
    - id: audit-logging
      severity: medium
      description: All workflow invocations must be logged
      eval: check_audit_log(request)
      onViolation: ESCALATE_HUMAN
  escalation:
    onReject: notify_human("Compliance violation: {{ .Rule.Description }}")
    onError: route_to_human("Judge error: {{ .Error }}")
```

### Agent (namespaced)

Single agent deployment — the primary CRD users create.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: Agent
metadata:
  name: engineering
  namespace: agents
spec:
  identity:
    displayName: "Engineering Agent"
    description: "Software engineering and architecture work"
    owner: "scott"
  config:
    agentConfigRef: standard-engineering
    overrides:
      resources:
        cpu: "4"
        memory: "8Gi"
  providers:
    - ref:
        name: openclaw-gateway
      model: deepseek-v4-flash:cloud
  channels:
    - ref:
        name: engineering-discord
  workflowTemplates:
    - ref:
        name: search-memory
    - ref:
        name: forgejo-pr-create
    - ref:
        name: file-write
  compliancePolicies:
    - ref:
        name: soc2-baseline
  judge:
    enabled: true
    providerRef:
      name: openclaw-gateway
    model: deepseek-v4-pro:cloud
```

### AgentGroup (namespaced)

Multi-agent orchestration with shared configs and per-member overrides.

```yaml
apiVersion: kubeclaw.nousresearch.com/v1alpha1
kind: AgentGroup
metadata:
  name: content-team
  namespace: agents
spec:
  sharedConfig:
    agentConfigRef: standard-content
    providers:
      - ref:
          name: openclaw-gateway
  members:
    - name: writer
      overrides:
        channels:
          - ref:
              name: content-discord
    - name: editor
      overrides:
        channels:
          - ref:
              name: editorial-slack
    - name: publisher
      overrides:
        channels:
          - ref:
              name: web-publish-discord
```

## Security Model

```
┌─────────────────────────────────────────────────────────────────────┐
│                    Agent Attack Surface                               │
│                                                                       │
│  Available tools: [template_workflow]                                 │
│  Not available: exec, write, web_search, sessions_*, forgejo_*,      │
│                 lean_experiment_*, cron, discord_send_raw              │
│                                                                       │
│  Judge validates every template_workflow call against:                │
│  ├─ WorkflowTemplate spec (schema, allowed steps)                     │
│  ├─ CompliancePolicy rules (SOC2/HIPAA/GDPR per-rule checks)          │
│  ├─ Agent-level whitelists (allowed templates, data boundaries)       │
│  └─ Regulatory framework system prompt                                │
│                                                                       │
│  Verdicts:                                                            │
│  ├─ APPROVE → workflow executor runs the steps                        │
│  ├─ REJECT → agent notified, human escalates if needed                │
│  └─ ESCALATE_HUMAN → routed to Scott with structured dispute          │
└─────────────────────────────────────────────────────────────────────┘
```

### Threat Model

| Threat | Mitigation |
|--------|-----------|
| Agent jailbreaks via prompt injection | Judge is separate model with no task-completion pressure; single-tool surface limits blast radius |
| Lateral movement between agents | Per-agent namespaces, NetworkPolicy isolation, strict Channel bindings |
| Privilege escalation via template params | WorkflowTemplate parameter validation, CompliancePolicy runtime checks |
| Data exfiltration via channels | Channel-scoped output validation, audit logging on every workflow step |
| Credential leak via log output | Secrets never injected into agent context; only referenced via `apiKeyRef` |
| Denial of service via resource exhaustion | Per-Agent resource limits, HPA on AgentGroup, OpenClaw gateway rate limiting |

## Project Structure

```
kubeclaw/
├── README.md                  # This file
├── config/
│   ├── crd/                   # CRD YAML definitions
│   │   ├── provider.yaml
│   │   ├── channel.yaml
│   │   ├── agentconfig.yaml
│   │   ├── workflowtemplate.yaml
│   │   ├── compliancepolicy.yaml
│   │   ├── agent.yaml
│   │   └── agentgroup.yaml
│   └── samples/               # Example CRD manifests
│       ├── sample-agent.yaml
│       ├── sample-group.yaml
│       └── sample-workflow.yaml
├── charts/
│   └── kubeclaw/             # Helm chart
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
│           ├── crds.yaml
│           ├── controller.yaml
│           ├── rbac.yaml
│           ├── service.yaml
│           └── webhook.yaml
├── internal/
│   ├── controller/           # Reconciler logic
│   │   ├── agent_controller.go
│   │   ├── agentgroup_controller.go
│   │   └── suite_test.go
│   ├── judge/                # Judge integration
│   │   ├── client.go
│   │   ├── verifier.go
│   │   └── types.go
│   └── webhook/              # Admission webhooks
│       ├── agent_validator.go
│       └── workflow_validator.go
├── docs/
│   ├── architecture.md       # Deep architecture doc
│   ├── development.md        # Dev setup guide
│   └── operator-lifecycle.md # Production operations
├── main.go                   # Entry point
├── go.mod
├── go.sum
├── Makefile
└── Dockerfile
```

## Quick Start

```bash
# Prerequisites
# - Go 1.22+
# - kubectl
# - kind or minikube (for local dev)
# - helm

# Clone the monorepo
git clone https://os.scoble.me/forgejo/marcus/scobleclaw.git
cd scobleclaw/kubeclaw

# Install CRDs
make install

# Run controller locally (against current kubecontext)
make run

# Deploy to cluster via Helm
helm install kubeclaw ./charts/kubeclaw --namespace kubeclaw-system --create-namespace

# Create a sample agent
kubectl apply -f config/samples/sample-agent.yaml
```

## Development

See [docs/development.md](docs/development.md) for detailed setup and workflow.

### Prerequisites

- Go 1.22+
- `controller-gen` (from sigs.k8s.io/controller-tools)
- `kustomize`
- `helm`
- Access to an OpenClaw gateway or compatible LLM API

### Commands

```bash
make generate    # Generate CRD deep copy and client code
make manifests   # Generate CRD YAML manifests
make test        # Run unit and integration tests
make run         # Run controller locally
make docker-build # Build controller image
make helm-package # Package Helm chart
```

## CRD Inventory

| CRD | Scope | Purpose |
|-----|-------|---------|
| Provider | Cluster | LLM provider configs (API keys, models, pricing) |
| Channel | Namespaced | Platform channel bindings (Discord, Slack, Telegram) |
| AgentConfig | Namespaced | Reusable agent configuration templates |
| WorkflowTemplate | Cluster | Pre-approved workflow templates (only thing agents can invoke) |
| CompliancePolicy | Cluster | Security/compliance evaluation rules for judge |
| Agent | Namespaced | Single agent deployment |
| AgentGroup | Namespaced | Multi-agent orchestration with shared configs |

## Integration: Agent Judge

This project integrates directly with the [Agent Judge architecture](https://os.scoble.me/forgejo/marcus/scobleclaw/issues/7):

- The **judge sidecar** implements the Judge protocol specified in `agent-judge-architecture.md`
- Risk classification from that architecture maps to CompliancePolicy CRD rules
- The `template_workflow` tool is the enforcement point — agents can only invoke what the judge has approved
- Admission webhooks validate CRD changes at the API server level (pre-commit)
- The judge validates at runtime (post-commit, pre-execution)

## License

MIT © Scott Scoble / Greybeard Holdings, LLC