scobleclaw/kubeclaw

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.

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.

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.

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.

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.

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.

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.

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

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

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:

• 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