Skip to content

Commit 349259d

Browse files
AlexsJonesAlexsJones
committed
docs: redesign README with Mermaid architecture diagram and badges
1 parent aa7fc2a commit 349259d

1 file changed

Lines changed: 75 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 75 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,79 @@
11
# K8sClaw
2-
---
2+
33
<p align="center">
44
<img src="icon.svg" alt="k8sclaw icon" width="128" height="128">
55
</p>
66

7-
**Kubernetes-native AI Agent Management Platform**
8-
9-
K8sClaw decomposes a monolithic AI agent gateway into a multi-tenant, horizontally scalable system where every sub-agent runs as an ephemeral Kubernetes pod.
10-
11-
### Quick install (macOS / Linux)
7+
<p align="center">
8+
<strong>Kubernetes-native AI Agent Management Platform</strong><br>
9+
<em>Decompose monolithic AI agent gateways into multi-tenant, horizontally scalable systems where every sub-agent runs as an ephemeral Kubernetes pod.</em>
10+
</p>
1211

13-
```bash
14-
curl -fsSL https://deploy.k8sclaw.ai/install.sh | sh
15-
```
12+
<p align="center">
13+
<a href="https://github.com/AlexsJones/k8sclaw/actions"><img src="https://github.com/AlexsJones/k8sclaw/actions/workflows/build.yaml/badge.svg" alt="Build"></a>
14+
<a href="https://github.com/AlexsJones/k8sclaw/releases/latest"><img src="https://img.shields.io/github/v/release/AlexsJones/k8sclaw" alt="Release"></a>
15+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
16+
</p>
1617

17-
Downloads the latest CLI binary from GitHub and installs it to `/usr/local/bin` (or `~/.local/bin`).
18+
---
1819

19-
### Deploy to your cluster
20+
### Quick Install (macOS / Linux)
2021

2122
```bash
22-
k8sclaw install
23+
curl -fsSL https://deploy.k8sclaw.ai/install.sh | sh
2324
```
2425

25-
That's it. This downloads the release manifests and applies CRDs, controllers, webhook, RBAC, and network policies to your current `kubectl` context.
26-
27-
To remove:
26+
### Deploy to Your Cluster
2827

2928
```bash
30-
k8sclaw uninstall
29+
k8sclaw install # CRDs, controllers, webhook, NATS, RBAC, network policies
30+
k8sclaw uninstall # clean removal
3131
```
3232

3333
## Architecture
3434

35-
```
36-
┌─────────────────────────────────────────────────────┐
37-
│ Control Plane │
38-
│ ┌──────────┐ ┌──────────┐ ┌────────────────────┐│
39-
│ │Controller │ │ API │ │ Admission ││
40-
│ │ Manager │ │ Server │ │ Webhook ││
41-
│ └────┬─────┘ └────┬─────┘ └────────────────────┘│
42-
│ │ │ │
43-
│ ┌────┴──────────────┴────┐ │
44-
│ │ NATS Event Bus │ │
45-
│ └────────────────────────┘ │
46-
│ │
47-
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
48-
│ │ Telegram │ │ Slack │ │ Discord │ ... │
49-
│ │ Channel │ │ Channel │ │ Channel │ │
50-
│ └──────────┘ └──────────┘ └──────────┘ │
51-
│ │
52-
│ ┌──────────────────────────────────────┐ │
53-
│ │ Agent Pods (ephemeral) │ │
54-
│ │ ┌─────────┐ ┌───────┐ ┌──────────┐ │ │
55-
│ │ │ Agent │ │ IPC │ │ Sandbox │ │ │
56-
│ │ │Container│ │Bridge │ │(optional)│ │ │
57-
│ │ └─────────┘ └───────┘ └──────────┘ │ │
58-
│ └──────────────────────────────────────┘ │
59-
└─────────────────────────────────────────────────────┘
35+
```mermaid
36+
graph TB
37+
subgraph CP["Control Plane"]
38+
CM[Controller Manager]
39+
API[API Server]
40+
WH[Admission Webhook]
41+
NATS[(NATS JetStream)]
42+
CM --- NATS
43+
API --- NATS
44+
WH -.- CM
45+
end
46+
47+
subgraph CH["Channel Pods"]
48+
TG[Telegram]
49+
SL[Slack]
50+
DC[Discord]
51+
WA[WhatsApp]
52+
end
53+
54+
subgraph AP["Agent Pods · ephemeral"]
55+
direction LR
56+
A1[Agent Container]
57+
IPC[IPC Bridge]
58+
SB[Sandbox]
59+
end
60+
61+
TG & SL & DC & WA --- NATS
62+
NATS --- IPC
63+
A1 -. "/ipc volume" .- IPC
64+
A1 -. optional .- SB
65+
66+
style CP fill:#1a1a2e,stroke:#e94560,color:#fff
67+
style CH fill:#16213e,stroke:#0f3460,color:#fff
68+
style AP fill:#0f3460,stroke:#53354a,color:#fff
69+
style NATS fill:#e94560,stroke:#fff,color:#fff
6070
```
6171

6272
## Custom Resources
6373

6474
| CRD | Description |
6575
|-----|-------------|
66-
| `ClawInstance` | Per-user/per-tenant gateway configuration |
76+
| `ClawInstance` | Per-user / per-tenant gateway configuration |
6777
| `AgentRun` | Ephemeral agent execution (maps to a K8s Job) |
6878
| `ClawPolicy` | Feature and tool gating policy |
6979
| `SkillPack` | Portable skill bundles (generates ConfigMaps) |
@@ -89,48 +99,36 @@ k8sclaw/
8999
│ ├── session/ # Session persistence (PostgreSQL)
90100
│ └── channel/ # Channel base types
91101
├── channels/ # Channel pod implementations
92-
│ ├── telegram/
93-
│ ├── whatsapp/
94-
│ ├── discord/
95-
│ └── slack/
96102
├── images/ # Dockerfiles
97103
├── config/ # Kubernetes manifests
98104
│ ├── crd/bases/ # CRD YAML definitions
99105
│ ├── manager/ # Controller + API server deployment
100106
│ ├── rbac/ # ServiceAccount, ClusterRole, bindings
101107
│ ├── webhook/ # Webhook deployment + configuration
102108
│ ├── network/ # NetworkPolicy for agent isolation
109+
│ ├── nats/ # NATS JetStream deployment
110+
│ ├── cert/ # TLS certificate resources
103111
│ └── samples/ # Example custom resources
104112
├── migrations/ # PostgreSQL schema migrations
105113
├── docs/ # Design documentation
106-
├── go.mod
107114
├── Makefile
108115
└── README.md
109116
```
110117

111118
## Prerequisites
112119

113120
- Kubernetes cluster (v1.28+)
114-
- NATS with JetStream enabled
115-
- PostgreSQL with pgvector extension
116121
- `kubectl` configured to your cluster
117122

118-
## Quick Start
123+
> NATS and cert-manager are installed automatically by `k8sclaw install`.
119124
120-
### Install the CLI
125+
## Quick Start
121126

122127
```bash
123-
# macOS / Linux
128+
# Install the CLI
124129
curl -fsSL https://deploy.k8sclaw.ai/install.sh | sh
125130

126-
# Or build from source
127-
make build-k8sclaw
128-
```
129-
130-
### Deploy K8sClaw
131-
132-
```bash
133-
# Install to your cluster
131+
# Deploy to your cluster
134132
k8sclaw install
135133

136134
# Or install a specific version
@@ -140,56 +138,37 @@ k8sclaw install --version v0.1.0
140138
kubectl apply -f https://raw.githubusercontent.com/AlexsJones/k8sclaw/main/config/samples/clawinstance_sample.yaml
141139
```
142140

143-
### Use the CLI
144-
145-
```bash
146-
# List instances
147-
k8sclaw instances list
148-
149-
# List agent runs
150-
k8sclaw runs list
151-
152-
# Enable a feature gate
153-
k8sclaw features enable browser-automation --policy default-policy
154-
155-
# List feature gates
156-
k8sclaw features list --policy default-policy
157-
```
158-
159-
### Remove K8sClaw
141+
### CLI Usage
160142

161143
```bash
162-
k8sclaw uninstall
144+
k8sclaw instances list # list instances
145+
k8sclaw runs list # list agent runs
146+
k8sclaw features enable browser-automation \
147+
--policy default-policy # enable a feature gate
148+
k8sclaw features list --policy default-policy # list feature gates
163149
```
164150

165151
## Development
166152

167153
```bash
168-
# Run tests
169-
make test
170-
171-
# Run linter
172-
make lint
173-
174-
# Generate CRD manifests
175-
make manifests
176-
177-
# Run the controller locally (requires kubeconfig)
178-
make run
154+
make test # run tests
155+
make lint # run linter
156+
make manifests # generate CRD manifests
157+
make run # run controller locally (needs kubeconfig)
179158
```
180159

181160
## Key Design Decisions
182161

183-
- **Ephemeral Agent Pods**: Each agent run creates a Kubernetes Job with a pod containing the agent container, IPC bridge sidecar, and optional sandbox sidecar
184-
- **IPC via filesystem**: Agent ↔ control plane communication uses filesystem-based IPC (`/ipc` volume) watched by the bridge sidecar, enabling language-agnostic agent implementations
185-
- **NATS JetStream**: Used as the event bus for decoupled inter-component communication with durable subscriptions
186-
- **NetworkPolicy isolation**: Agent pods run with deny-all network policies; only the IPC bridge sidecar connects to the event bus
187-
- **Policy-as-CRD**: ClawPolicy resources gate tool access, sandbox requirements, and feature flags, enforced by admission webhooks
162+
| Decision | Rationale |
163+
|----------|-----------|
164+
| **Ephemeral Agent Pods** | Each agent run creates a K8s Job — agent container + IPC bridge sidecar + optional sandbox |
165+
| **Filesystem IPC** | Agent ↔ control plane via `/ipc` volume watched by the bridge sidecar — language-agnostic |
166+
| **NATS JetStream** | Decoupled event bus with durable subscriptions |
167+
| **NetworkPolicy isolation** | Agent pods get deny-all; only the IPC bridge connects to the bus |
168+
| **Policy-as-CRD** | `ClawPolicy` resources gate tools, sandboxes, and feature flags via admission webhooks |
188169

189170
## Configuration
190171

191-
### Environment Variables
192-
193172
| Variable | Component | Description |
194173
|----------|-----------|-------------|
195174
| `EVENT_BUS_URL` | All | NATS server URL |

0 commit comments

Comments
 (0)