From 74aaacf4cd57a9fee57357d0e4fcbf35988bbb59 Mon Sep 17 00:00:00 2001 From: Pal Lakatos-Toth Date: Mon, 27 Apr 2026 15:20:41 +0200 Subject: [PATCH] docs(readme,blueprints): broaden audience + unify mermaid theming MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README: - Add a hint that today AzureClaw hosts OpenClaw but the same guardrails (Workload-Identity inference, Confidential Containers, Signal mesh, AGT, audit) extend to any agentic runtime — MCP / A2A / AP2 scaffolding is already in the codebase so LangGraph / AutoGen / CrewAI / SK can be hosted in the same sandbox over the wire. - Add a 'Hardware-isolated cloud offload' bullet pointing at Blueprint 03, framed as 'not just for enterprises' — any managed provider (small MSPs, indie SaaS, hobbyist co-ops) can offer a confidential sandbox to end users whose home setup doesn't fit the job (heavier models, longer runs, parallel fan-out, premium-quota work). Blueprint 03 (managed public offload): - Reframe persona from 'SaaS provider' to 'managed-AzureClaw provider at any scale', with concrete customer examples (indie devs, researchers, field engineers, privacy-sensitive users). - Note that the security shape is identical regardless of provider size. Blueprint diagrams: - Add a unified %%{init}%% theme directive (theme: base with neutral slate themeVariables) to all 15 mermaid blocks across 01-05 so they render consistently in both GitHub light and dark mode and stop looking like a mix of light/dark. - Normalise the one outlier classDef fill in 02 (#f0f7ff -> #dbeafe) so the cool-blue 'boundary' shade matches the cool-blue 'provider' shade used in 03 and 04. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 3 +++ docs/blueprints/01-developer-inner-loop.md | 2 ++ docs/blueprints/02-enterprise-self-hosted.md | 5 ++++- docs/blueprints/03-managed-public-offload.md | 13 ++++++++++--- docs/blueprints/04-cross-org-federation.md | 3 +++ docs/blueprints/05-sovereign-airgapped.md | 3 +++ 6 files changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6ed222890..b2a58ba7c 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,8 @@ Every agent runs inside a hardened sandbox pod. A Rust inference router sits in AzureClaw is **not a fork of OpenClaw** — it extends OpenClaw via its native plugin API and `tools.deny` config, so any upstream OpenClaw release is drop-in compatible. See [Upstream Alignment](docs/upstream-alignment.md). +> **Today: OpenClaw. Tomorrow: any agentic runtime.** The guardrails — Workload-Identity-fronted inference, Confidential-Container sandboxing, Signal-Protocol mesh, AGT governance, tamper-evident audit — are runtime-agnostic by design. The plugin/`tools.deny` approach only happens to be how we hook OpenClaw; the protocol scaffolding for **MCP**, **A2A**, and **AP2** is already in the codebase so the same sandbox can host LangGraph, AutoGen, CrewAI, Semantic Kernel, or anything else that speaks one of those wire formats. See the [Roadmap](#roadmap-extending-beyond-openclaw) and [Scenario 4 in `docs/use-cases.md`](docs/use-cases.md). + ### Who is this for? - **Platform teams** who need to host LLM agents on AKS with the same operational rigour as the rest of their workloads — namespace isolation, RBAC, NetworkPolicies, audit, signed admission. @@ -43,6 +45,7 @@ AzureClaw is **not a fork of OpenClaw** — it extends OpenClaw via its native p 3. **Inter-agent trust** — agents talk over a Signal-Protocol mesh with explicit KNOCK trust handshake, trust scoring, and tamper-evident audit chain. No plaintext fallback. 4. **Operational footprint** — `azureclaw up` provisions AKS + ACR + Foundry + Foundry-side Content Safety + sandbox in one go; `azureclaw operator` gives a live TUI for running fleets. 5. **Multi-runtime future** — see [Roadmap](#roadmap-extending-beyond-openclaw) below: protocol scaffolding (MCP, A2A, AP2) is in place so the same sandbox can host non-OpenClaw agents over the wire. +6. **Hardware-isolated cloud offload** — run customer agents in Kata + AMD SEV-SNP confidential containers so even a compromised cluster-admin cannot read prompts in flight. See [Blueprint 03 — Managed public offload](docs/blueprints/03-managed-public-offload.md): not just for enterprises, but for **any managed provider** — small MSPs, indie SaaS, hobbyist co-ops — letting end users offload tasks that don't fit a home setup (heavier models, longer runs, parallel fan-out, jobs requiring premium quota) to a sandbox they don't have to operate themselves. > 📖 **See [`docs/use-cases.md`](docs/use-cases.md)** for the four end-to-end scenarios — AzureClaw-native agents, **any-OpenClaw → AzureClaw cloud offload** (no AzureClaw CLI on the laptop), AzureClaw ↔ AzureClaw mesh, and the roadmap for non-OpenClaw runtimes via MCP / A2A / AP2. For deployment shapes (developer inner-loop, enterprise self-hosted, managed public offload, cross-org federation, sovereign / air-gapped) with topology + trust-boundary + flow diagrams, see [`docs/blueprints/`](docs/blueprints/00-index.md). diff --git a/docs/blueprints/01-developer-inner-loop.md b/docs/blueprints/01-developer-inner-loop.md index 699f54bb9..58d9d4517 100644 --- a/docs/blueprints/01-developer-inner-loop.md +++ b/docs/blueprints/01-developer-inner-loop.md @@ -11,6 +11,7 @@ ## Topology ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart LR subgraph Laptop["💻 Laptop (your machine)"] direction TB @@ -58,6 +59,7 @@ The only thing that's *not* like production is the host: `kind` instead of AKS, ## Primary flow ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% sequenceDiagram autonumber participant Dev as 👤 You diff --git a/docs/blueprints/02-enterprise-self-hosted.md b/docs/blueprints/02-enterprise-self-hosted.md index 73f9d0d51..b0c548096 100644 --- a/docs/blueprints/02-enterprise-self-hosted.md +++ b/docs/blueprints/02-enterprise-self-hosted.md @@ -11,6 +11,7 @@ ## Topology ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart TB subgraph Corp["🏢 Your organisation (single Entra tenant)"] direction TB @@ -73,6 +74,7 @@ flowchart TB ## Trust boundary ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart LR subgraph TB1["🏢 Corp Entra tenant + VNet"] direction TB @@ -86,7 +88,7 @@ flowchart LR AKS -->|"Workload Identity"| FND AKS -->|"audit"| LAW - classDef boundary stroke:#0078d4,stroke-width:3px,fill:#f0f7ff; + classDef boundary stroke:#1e40af,stroke-width:3px,fill:#dbeafe; class TB1 boundary; ``` @@ -97,6 +99,7 @@ flowchart LR ## Primary flow — onboarding a new employee laptop ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% sequenceDiagram autonumber participant Eng as 👤 Engineer diff --git a/docs/blueprints/03-managed-public-offload.md b/docs/blueprints/03-managed-public-offload.md index 38dc9aec3..7cafe0b63 100644 --- a/docs/blueprints/03-managed-public-offload.md +++ b/docs/blueprints/03-managed-public-offload.md @@ -1,6 +1,6 @@ # Blueprint 03 — Managed public offload service -> "I'm a SaaS provider. I want to run AzureClaw as a managed offload service for many external customers — each one a different Entra tenant, none of them with kubectl access, all of them onboarded by token, all of them isolated from each other and from me at every layer, including the host kernel." +> "I run a managed AzureClaw offering. Maybe I'm a hyperscale SaaS, maybe I'm a 3-person MSP, maybe I'm a community co-op renting capacity to hobbyists. My customers want to offload heavier or sensitive agent tasks — bigger models, longer runs, parallel fan-out — that don't fit on their laptops. I want to host them all on one cluster, in different Entra tenants, none with kubectl access, all onboarded by token, all isolated from each other and from me at every layer including the host kernel." > **Status: ✅ Runtime shipping. 🚧 SaaS productization in progress.** The hardware-isolated sandbox runtime, the pairing protocol, the per-tenant namespace + Workload Identity scoping, the confidential-mode Kata VM + AMD SEV-SNP nodepool, the audit chain, and the Foundry-side Content Safety are all validated end-to-end on live AKS today (see [`docs/security-validation.md`](../security-validation.md)). What's "🚧" is the *SaaS wrapper* around it: portal + billing + automated onboarding + per-tenant Foundry-quota sharding. The scary parts (isolation + crypto) are not the parts that need productizing. @@ -8,6 +8,8 @@ This is the use case where AzureClaw's threat model earns its complexity. In every other blueprint, you (the operator) and the agent user are in the same trust domain — you'd both lose if a sandbox escaped. Here, **the provider is one of the parties the customer is defending against**: a malicious or compromised provider operator could otherwise tail a customer's prompts, exfiltrate their files, or impersonate them to upstream services. +The customers don't have to be enterprises either. The same primitives that let a Fortune-500 trust a hyperscaler also let a hobbyist trust a 3-person MSP, or a researcher trust a community co-op renting GPU time. The economic shape changes (one tenant per customer, not one tenant per business unit); the security shape doesn't. + AzureClaw makes that attack mathematically infeasible by stacking three independent isolation primitives: 1. **Signal-Protocol mesh** — the relay sees only ciphertext (X3DH + Double Ratchet). The provider can't read what the customer sent over the wire even with a `tcpdump` on the cluster ingress. @@ -18,13 +20,15 @@ Net effect: the customer's cleartext exists for ~milliseconds, only inside an SE ## Persona & intent -- **You are:** the SaaS provider running an AzureClaw cloud. Your customers run OpenClaw / NemoClaw / any-OpenClaw on their laptops, in their offices, in their own clusters — anywhere — and offload heavy or sensitive tasks to your AKS. -- **You want:** a single AKS cluster (or a few regional clusters) hosting many tenants. Self-service onboarding via your portal. Per-tenant token budgets, slot caps, capability scopes. Provider-side observability without ever decrypting customer mesh traffic. +- **You are:** a managed-AzureClaw provider — at any scale. A hyperscaler running a public offering. A regional MSP white-labelling agentic compute. A 3-person team renting GPU minutes. A community co-op pooling capacity for hobbyists. Your customers run OpenClaw / NemoClaw / any-OpenClaw on their laptops, in their offices, in their own clusters — anywhere — and offload tasks they can't (or don't want to) run locally to your AKS. +- **Who your customers are:** anyone whose home setup doesn't fit the job. Indie devs who need a 70B model their MacBook can't host. Researchers parallelising 1,000 prompts overnight. Field engineers offloading a long-running agent so their laptop can sleep. Privacy-sensitive users who'd rather rent a confidential sandbox than send prompts to an LLM proxy that logs everything. Enterprises picking a smaller specialist provider over a hyperscaler for compliance or cost reasons. +- **You want:** a single AKS cluster (or a few regional clusters) hosting many tenants. Self-service onboarding via your portal (or a Telegram bot, or a CLI sub-command — pairing is just a one-time token). Per-tenant token budgets, slot caps, capability scopes. Provider-side observability without ever decrypting customer mesh traffic. - **You do not want:** to ever hold customer-side LLM context in cleartext on a host you control. To require customers to install your CLI. To leak one tenant's audit chain to another. To have a cluster-admin compromise read customer prompts in flight. ## Topology ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart TB subgraph Provider["☁️ Provider AKS (multi-tenant)"] direction TB @@ -95,6 +99,7 @@ flowchart TB ## The hardware-isolated sandbox (where the magic is) ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart TB subgraph Host["AKS host node (Standard_DCa_v6 — AMD EPYC w/ SEV-SNP)"] direction TB @@ -156,6 +161,7 @@ flowchart TB ## Trust boundary ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart LR subgraph Cust["Customer trust domain"] UserCtx["agent context, prompts,
files (cleartext)"] @@ -196,6 +202,7 @@ The crucial property: **the provider's trust domain (the AKS cluster, the relay, ## Primary flow — customer signs up + offloads a confidential task ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% sequenceDiagram autonumber participant Cust as 👤 Customer dev diff --git a/docs/blueprints/04-cross-org-federation.md b/docs/blueprints/04-cross-org-federation.md index 35e99b1fb..1e09d874f 100644 --- a/docs/blueprints/04-cross-org-federation.md +++ b/docs/blueprints/04-cross-org-federation.md @@ -11,6 +11,7 @@ ## Topology ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart TB subgraph OrgA["🏢 Org A — Entra tenant A, AKS A"] direction TB @@ -52,6 +53,7 @@ flowchart TB ## Trust boundary ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart LR subgraph A["Org A trust domain"] PA["AGT policy A
(ingress + egress)"] @@ -90,6 +92,7 @@ Neither side relies on the other's audit chain. Both sides write their own. ## Primary flow — pairing two clusters, then a handoff ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% sequenceDiagram autonumber participant OpsA as Ops A diff --git a/docs/blueprints/05-sovereign-airgapped.md b/docs/blueprints/05-sovereign-airgapped.md index baadbf3a5..ef7dd86a7 100644 --- a/docs/blueprints/05-sovereign-airgapped.md +++ b/docs/blueprints/05-sovereign-airgapped.md @@ -13,6 +13,7 @@ ## Topology ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart TB subgraph AirGap["🔒 Air-gapped network island"] direction TB @@ -65,6 +66,7 @@ flowchart TB ## Trust boundary ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% flowchart TB subgraph Inside["🔒 Air-gapped trust domain"] direction LR @@ -87,6 +89,7 @@ The trust boundary is the **network island**. Nothing inside it talks to anythin ## Primary flow — bundle build, transfer, install ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f1f5f9','primaryBorderColor':'#475569','primaryTextColor':'#0f172a','lineColor':'#475569','clusterBkg':'#f8fafc','clusterBorder':'#94a3b8','fontFamily':'-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif'}}}%% sequenceDiagram autonumber participant Build as build host (online)