OpenShield

v1.0.0

One command to run OpenClaw on Docker or Kubernetes, with an OpenShield security hook layer installed inside the runtime.

npx openshield@latest init

OpenShield no longer connects agents to a hosted dashboard. Setup is local: pick a runtime, start the official OpenClaw image, enable security hooks, and write project artifacts under .openshield/.

Why OpenShield?

| Without OpenShield | With OpenShield | |--------------------|-----------------| | Manual Compose/K8s manifests | Generated project under .openshield/ | | OpenClaw image only | Image plus managed security hooks | | Default exec trust model | cautious / yolo / deny-all presets | | No audit trail by default | Local JSONL logs under ~/.openclaw/logs/ |

Quick start

Interactive (recommended)

npx openshield@latest init

You will be asked:

1. Docker or Kubernetes
2. Project directory, container image, gateway port, exec policy
3. Whether to apply the security hook layer

OpenShield then writes files, starts OpenClaw, installs hooks, and prints the gateway URL and token location.

Non-interactive

# Docker (Compose v2)
npx openshield@latest init --yes --runtime docker

# Kubernetes (current kube context)
npx openshield@latest init --yes --runtime kubernetes --namespace openclaw

# Local kind cluster, then deploy
npx openshield@latest init --yes --runtime kubernetes --create-kind

# Custom image / port
npx openshield@latest init --yes --runtime docker \
  --image ghcr.io/openclaw/openclaw:latest \
  --port 18789 \
  --exec-policy cautious

After init

Docker

Gateway:  http://127.0.0.1:18789/
Token:    .openshield/docker/.env  →  OPENCLAW_GATEWAY_TOKEN
Compose:  .openshield/docker/docker-compose.yml

cd .openshield/docker
docker compose logs -f
docker compose exec openclaw-gateway openclaw hooks list
docker compose down

Kubernetes

Access:   kubectl port-forward svc/openclaw 18789:18789 -n openclaw
Token:    .openshield/k8s/gateway-token.txt
Manifests:.openshield/k8s/

kubectl get all -n openclaw
kubectl logs -n openclaw -l app=openclaw -f
kubectl exec -n openclaw deploy/openclaw -- openclaw hooks list
kubectl delete namespace openclaw   # tear down

Both paths also write a SECURITY.md checklist in the project directory.

What init does

| Step | Docker | Kubernetes | |------|--------|------------| | Detect tooling | docker + Compose v2 | kubectl (+ optional kind) | | Write project files | .openshield/docker/ | .openshield/k8s/*.yaml | | Start OpenClaw | docker compose up -d | kubectl apply + rollout wait | | Image (default) | ghcr.io/openclaw/openclaw:latest | same (--image to override) | | Security hooks | Copy into container state + enable | kubectl cp into pod + enable | | Policy / audit | exec-policy + security audit --fix (best-effort) | same | | Docs | SECURITY.md | same |

Gateway auth uses a generated token (OPENCLAW_GATEWAY_TOKEN). Pass --token to set your own.

Security hook layer

Hooks are installed into the runtime’s OpenClaw state (~/.openclaw/hooks/ inside the container/pod):

| Hook | Kind | Purpose | Log / effect | |------|------|---------|--------------| | openshield-security | OpenShield | Commands, gateway startup, compaction | ~/.openclaw/logs/openshield-security.jsonl | | openshield-message-guard | OpenShield | Inbound/outbound message metadata + light flags | ~/.openclaw/logs/openshield-messages.jsonl | | command-logger | Bundled | Command audit | ~/.openclaw/logs/commands.log | | session-memory | Bundled | Snapshot on /new / /reset | workspace memory/ |

Also applied (best-effort inside the runtime):

• openclaw exec-policy preset <cautious|yolo|deny-all>
• openclaw security audit --fix
• hooks.internal.enabled=true

Message body logging (opt-in)

By default, message bodies are not stored (metadata + length only). To include a short preview:

export OPENSHIELD_LOG_MESSAGE_BODIES=1
# restart the gateway container / pod

Re-apply security on a host install

If you run OpenClaw on the host (not only in containers):

npx openshield@latest install    # optional: npm i -g openclaw
npx openshield@latest harden     # hooks + policy + audit on ~/.openclaw

Commands

| Command | Description | |---------|-------------| | openshield init | Primary: Docker or K8s + OpenClaw + security hooks | | openshield status | Detect docker/kubectl; show host OpenClaw status | | openshield status --audit | Include host security audit JSON when available | | openshield install | Install OpenClaw CLI on the host only | | openshield harden | Security layer on a host OpenClaw install |

Global options

| Flag | Description | |------|-------------| | -y, --yes | Non-interactive defaults | | --openclaw-root <path> | Host state dir for harden / status (default ~/.openclaw) | | -V, --version | Print version (1.0.0) |

init options

| Flag | Description | Default | |------|-------------|---------| | --runtime docker\|kubernetes | Runtime (with --yes, skips prompt) | auto: docker if available | | --image <ref> | Container image | ghcr.io/openclaw/openclaw:latest | | --port <n> | Gateway port | 18789 | | --namespace <ns> | Kubernetes namespace | openclaw | | --workdir <path> | Where .openshield/ is written | current directory | | --exec-policy cautious\|yolo\|deny-all | Host-exec policy inside runtime | cautious | | --create-kind | Create kind cluster openshield | off | | --skip-harden | Skip hooks / audit inside runtime | off | | --token <token> | Gateway token | auto-generated |

Exec policy presets

| Preset | Intent | |--------|--------| | cautious | Recommended — approvals for risky host exec | | yolo | Trusted single-operator; minimal prompts | | deny-all | Block host exec |

Prerequisites

Docker path

• Docker Engine or Docker Desktop
• Compose v2: docker compose version
• Enough disk/RAM to pull the OpenClaw image (~multi‑GB unpack)

Kubernetes path

• kubectl with a working context (k3s, kind, minikube, EKS, GKE, AKS, …), or
• kind and --create-kind for a local cluster
• Cluster able to pull ghcr.io/openclaw/openclaw (or your --image)
• Storage class that can bind a 10Gi PVC (default request)

Node (for the OpenShield CLI)

• Node.js 20+ (CLI only; OpenClaw runs in the container)

Project layout after init

.
├── SECURITY.md                 # operator checklist (runtime-specific notes)
└── .openshield/
    ├── docker/                 # if --runtime docker
    │   ├── docker-compose.yml
    │   ├── .env                # OPENCLAW_GATEWAY_TOKEN (mode 600)
    │   └── hooks/              # staged OpenShield hooks
    └── k8s/                    # if --runtime kubernetes
        ├── namespace.yaml
        ├── secret.yaml
        ├── pvc.yaml
        ├── configmap.yaml
        ├── deployment.yaml
        ├── service.yaml
        ├── gateway-token.txt
        └── hooks/

Add .openshield/docker/.env and .openshield/k8s/gateway-token.txt to .gitignore if you commit the rest of the project.

Programmatic API

import {
  init,
  detectRuntimes,
  initDocker,
  initKubernetes,
  harden,
  getStatus,
} from 'openshield';

const available = await detectRuntimes();
// { docker: { ok, compose, ... }, kubernetes: { ok, context, ... } }

const result = await init({
  runtime: 'docker',
  workDir: process.cwd(),
  execPolicy: 'cautious',
});

console.log(result.gatewayUrl, result.gatewayToken);

// Host-only hardening
// await harden({ execPolicy: 'cautious', workspace: process.cwd() });

Migration from 0.4–0.7

| Removed (0.x dashboard era) | 0.9 replacement | |-----------------------------|-----------------| | Dashboard heartbeat / Supabase agent-api | Local JSONL under ~/.openclaw/logs/ | | orientation/API_creds.md | SECURITY.md + .openshield/** tokens | | openshield tui | Interactive init prompts | | Host-only “add agent + start gateway” as primary | Docker / Kubernetes as primary | | Reporting helpers (heartbeat, reportTask, …) | Removed from public API |

npx [email protected] init --yes --runtime docker

Development

git clone https://github.com/deliverydriver/openshield.git
cd openshield
npm install
npm run build
npm test
npm run verify

| Script | Purpose | |--------|---------| | npm run build | Bundle CLI + library to dist/ | | npm test | Build + node:test suite | | npm run verify | test + CLI help + npm pack --dry-run | | npm run dev | tsx src/cli.ts |

Published package contents: dist/, hooks/, templates/.

Related docs

• OpenClaw — Docker
• OpenClaw — Kubernetes
• OpenClaw — Hooks
• OpenClaw — Security
• OpenClaw — security CLI

License

MIT · openshield.cc · github.com/deliverydriver/openshield