|
| 1 | +# Integrating with NVIDIA OpenShell |
| 2 | + |
| 3 | +Deploy the Agent Governance Toolkit as the governance layer inside (or alongside) [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes to combine **runtime isolation** with **governance intelligence**. |
| 4 | + |
| 5 | +> **TL;DR** — OpenShell provides the *walls* (sandbox, network, filesystem policies). The toolkit provides the *brain* (identity, trust, policy decisions, audit). Together they form a complete agent security stack. |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## Why Combine Them? |
| 10 | + |
| 11 | +OpenShell and the Agent Governance Toolkit solve **different halves** of the agent security problem: |
| 12 | + |
| 13 | +| Capability | OpenShell | Governance Toolkit | |
| 14 | +|---|:---:|:---:| |
| 15 | +| Container isolation | ✅ | — | |
| 16 | +| Filesystem policies | ✅ | — | |
| 17 | +| Network egress control | ✅ | — | |
| 18 | +| Process / syscall restrictions | ✅ | — | |
| 19 | +| Inference routing | ✅ | — | |
| 20 | +| Agent identity (Ed25519 DIDs) | — | ✅ | |
| 21 | +| Behavioral trust scoring | — | ✅ | |
| 22 | +| Policy engine (YAML + OPA + Cedar) | — | ✅ | |
| 23 | +| Authority resolution (reputation-gated delegation) | — | ✅ | |
| 24 | +| Tamper-evident Merkle audit chains | — | ✅ | |
| 25 | +| SLOs, circuit breakers, execution rings | — | ✅ | |
| 26 | +| Multi-agent governance | — | ✅ | |
| 27 | + |
| 28 | +OpenShell asks: *"Is this network call allowed by sandbox policy?"* |
| 29 | +The toolkit asks: *"Should this agent be trusted to make this call at all?"* |
| 30 | + |
| 31 | +Neither replaces the other — they're complementary layers in a defense-in-depth stack. |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +## Architecture |
| 36 | + |
| 37 | +``` |
| 38 | +┌──────────────────────────────────────────────────────────────────┐ |
| 39 | +│ OpenShell Sandbox │ |
| 40 | +│ │ |
| 41 | +│ ┌────────────────────────┐ ┌────────────────────────────────┐ │ |
| 42 | +│ │ AI Agent (Claude, │ │ Governance Toolkit (sidecar) │ │ |
| 43 | +│ │ Codex, OpenCode, etc) │ │ │ │ |
| 44 | +│ │ │ │ AgentIdentity — Ed25519 DIDs │ │ |
| 45 | +│ │ Tool call ────────────────► PolicyEngine — YAML/OPA/Cedar│ │ |
| 46 | +│ │ ◄────────────── RewardService — trust scoring │ │ |
| 47 | +│ │ (allow / deny) │ │ AuditLog — Merkle chain │ │ |
| 48 | +│ │ │ │ AuthorityResolver — delegation │ │ |
| 49 | +│ └────────────────────────┘ └────────────────────────────────┘ │ |
| 50 | +│ │ |
| 51 | +│ ┌──────────────────────────────────────────────────────────────┐ │ |
| 52 | +│ │ OpenShell Policy Engine │ │ |
| 53 | +│ │ Filesystem ▸ Network ▸ Process ▸ Inference │ │ |
| 54 | +│ └──────────────────────────────────────────────────────────────┘ │ |
| 55 | +└──────────────────────────────────────────────────────────────────┘ |
| 56 | +``` |
| 57 | + |
| 58 | +**Request flow:** |
| 59 | + |
| 60 | +1. Agent issues a tool call (e.g., `shell:curl`, `file:write`) |
| 61 | +2. **Governance Toolkit** evaluates: identity verified? trust score above threshold? policy allows action? authority delegated? |
| 62 | +3. If governance approves → OpenShell's **sandbox policy engine** enforces runtime constraints (network egress, filesystem boundaries, process restrictions) |
| 63 | +4. Both layers log independently — governance writes to the Merkle audit chain, OpenShell writes to its own policy log |
| 64 | +5. If either layer denies → action is blocked |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## Setup |
| 69 | + |
| 70 | +### Option A: Governance Skill Inside the Sandbox |
| 71 | + |
| 72 | +Install the toolkit as an [OpenClaw skill](../packages/agentmesh-integrations/openclaw-skill/) that the agent invokes before each action: |
| 73 | + |
| 74 | +```bash |
| 75 | +# Inside the sandbox |
| 76 | +pip install agentmesh |
| 77 | + |
| 78 | +# Use the skill scripts |
| 79 | +scripts/check-policy.sh --action "web_search" --tokens 1500 --policy policy.yaml |
| 80 | +scripts/trust-score.sh --agent "did:mesh:abc123" |
| 81 | +scripts/verify-identity.sh --did "did:mesh:abc123" --message "hello" --signature "base64sig" |
| 82 | +``` |
| 83 | + |
| 84 | +This approach is lightweight and works with any agent that supports OpenClaw skills. |
| 85 | + |
| 86 | +### Option B: Governance Sidecar (Production) |
| 87 | + |
| 88 | +Run the toolkit as a sidecar proxy that intercepts all tool calls transparently: |
| 89 | + |
| 90 | +```yaml |
| 91 | +# openshell-governance-policy.yaml |
| 92 | +network: |
| 93 | + outbound: |
| 94 | + - match: |
| 95 | + host: "localhost" |
| 96 | + port: 8081 |
| 97 | + action: allow # Allow agent → governance sidecar |
| 98 | + - match: |
| 99 | + host: "*.openai.com" |
| 100 | + action: allow # Allow approved LLM calls |
| 101 | + - action: deny # Block everything else |
| 102 | + |
| 103 | +filesystem: |
| 104 | + read: |
| 105 | + - /workspace/** |
| 106 | + - /policies/** |
| 107 | + write: |
| 108 | + - /workspace/** |
| 109 | + - /var/log/governance/** |
| 110 | +``` |
| 111 | +
|
| 112 | +```bash |
| 113 | +# Start the governance sidecar inside the sandbox |
| 114 | +python -m agentmesh.server --port 8081 --policy /policies/ & |
| 115 | + |
| 116 | +# Create the sandbox with the policy |
| 117 | +openshell sandbox create \ |
| 118 | + --policy openshell-governance-policy.yaml \ |
| 119 | + -- claude |
| 120 | +``` |
| 121 | + |
| 122 | +See the full [OpenClaw sidecar deployment guide](../deployment/openclaw-sidecar.md) for AKS and Docker Compose configurations. |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## Policy Layering Example |
| 127 | + |
| 128 | +A single agent action passes through **two policy layers**: |
| 129 | + |
| 130 | +``` |
| 131 | +Agent: "I want to POST to https://api.github.com/repos/org/repo/issues" |
| 132 | +
|
| 133 | +Layer 1 — Governance Toolkit: |
| 134 | + ✅ Agent identity verified (did:mesh:a1b2c3) |
| 135 | + ✅ Trust score 0.82 > threshold 0.5 |
| 136 | + ✅ Policy allows "http:POST:api.github.com/*" |
| 137 | + ✅ Authority: delegated by parent agent with scope "github:issues:create" |
| 138 | + → ALLOW (logged to Merkle audit chain) |
| 139 | +
|
| 140 | +Layer 2 — OpenShell: |
| 141 | + ✅ Network policy permits POST to api.github.com |
| 142 | + ✅ Process policy permits curl binary |
| 143 | + → ALLOW (logged to OpenShell policy log) |
| 144 | +
|
| 145 | +Result: Action executes |
| 146 | +``` |
| 147 | + |
| 148 | +If either layer denies: |
| 149 | + |
| 150 | +``` |
| 151 | +Agent: "I want to POST to https://169.254.169.254/metadata" |
| 152 | +
|
| 153 | +Layer 1 — Governance Toolkit: |
| 154 | + ❌ Policy blocks "http:*:169.254.169.254/*" (cloud metadata endpoint) |
| 155 | + → DENY (logged with violation reason) |
| 156 | +
|
| 157 | +Result: Action blocked before reaching OpenShell |
| 158 | +``` |
| 159 | + |
| 160 | +--- |
| 161 | + |
| 162 | +## OpenShell Policy + Governance Policy Mapping |
| 163 | + |
| 164 | +| OpenShell Layer | Governance Toolkit Equivalent | How They Interact | |
| 165 | +|---|---|---| |
| 166 | +| `filesystem.read/write` | Capability policies (`file:read:*`, `file:write:*`) | Governance decides *who can*, OpenShell enforces *where* | |
| 167 | +| `network.outbound` | Capability policies (`http:GET:*`, `http:POST:*`) | Governance decides *what action*, OpenShell enforces *which endpoints* | |
| 168 | +| `process` | Blocked-tool policies, execution rings | Governance gates by trust level, OpenShell gates by syscall | |
| 169 | +| `inference` routing | N/A (complementary) | OpenShell routes LLM traffic; governance audits responses | |
| 170 | +| N/A | Identity, trust scoring, audit | Governance-only capabilities | |
| 171 | + |
| 172 | +--- |
| 173 | + |
| 174 | +## Monitoring |
| 175 | + |
| 176 | +When running both layers, you get two complementary telemetry streams: |
| 177 | + |
| 178 | +**Governance Toolkit metrics** (Prometheus / OpenTelemetry): |
| 179 | +- `policy_decisions_total{result="allow|deny"}` |
| 180 | +- `trust_score_current{agent="did:mesh:..."}` |
| 181 | +- `audit_chain_entries_total` |
| 182 | +- `authority_resolutions_total{decision="allow|deny|narrowed"}` |
| 183 | + |
| 184 | +**OpenShell metrics**: |
| 185 | +- Sandbox network egress logs |
| 186 | +- Filesystem access logs |
| 187 | +- Process execution logs |
| 188 | +- Inference routing logs |
| 189 | + |
| 190 | +Both can feed into the same Grafana dashboard for a unified view. See the [Agent SRE monitoring guide](../../packages/agent-sre/README.md) for SLO configuration. |
| 191 | + |
| 192 | +--- |
| 193 | + |
| 194 | +## FAQ |
| 195 | + |
| 196 | +**Q: Do I need both?** |
| 197 | +No. Each works independently. But together they provide defense-in-depth: governance intelligence (who, what, why) plus runtime isolation (where, how). |
| 198 | + |
| 199 | +**Q: Does the toolkit work with agents other than OpenClaw?** |
| 200 | +Yes. The toolkit is agent-agnostic — it works with any AI agent framework (LangChain, CrewAI, AutoGen, Semantic Kernel, etc.) on any cloud (AWS, GCP, Azure) or locally. |
| 201 | + |
| 202 | +**Q: Does OpenShell replace the sidecar deployment?** |
| 203 | +OpenShell can *host* the sidecar. The governance sidecar runs inside or alongside the OpenShell sandbox. OpenShell provides the isolation boundary; the sidecar provides the governance logic. |
| 204 | + |
| 205 | +**Q: What about NemoClaw?** |
| 206 | +[NemoClaw](https://nvidianews.nvidia.com/news/ai-agents) bundles OpenShell with NVIDIA Nemotron models. The governance toolkit works with NemoClaw the same way — it adds identity, trust, and audit capabilities on top of the NemoClaw runtime. |
| 207 | + |
| 208 | +--- |
| 209 | + |
| 210 | +## Related |
| 211 | + |
| 212 | +- [OpenClaw Skill](../../packages/agentmesh-integrations/openclaw-skill/) — Lightweight skill for OpenClaw agents |
| 213 | +- [OpenClaw Sidecar Deployment](../deployment/openclaw-sidecar.md) — AKS and Docker Compose guide |
| 214 | +- [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) — Runtime sandbox for AI agents |
| 215 | +- [Architecture](../ARCHITECTURE.md) — Full toolkit architecture |
0 commit comments