Skip to content

Add blackwall-guard example — BLACK_WALL pre-action risk gate for OpenClaw agents - #52

Open
bluetieroperations-create wants to merge 1 commit into
NVIDIA:mainfrom
bluetieroperations-create:add-blackwall-guard-example
Open

Add blackwall-guard example — BLACK_WALL pre-action risk gate for OpenClaw agents#52
bluetieroperations-create wants to merge 1 commit into
NVIDIA:mainfrom
bluetieroperations-create:add-blackwall-guard-example

Conversation

@bluetieroperations-create

@bluetieroperations-create bluetieroperations-create commented Jul 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What this adds

examples/blackwall-guard/ — a community integration that adds a pre-action risk gate to an OpenClaw agent running under NemoClaw. It hooks before_tool_call and screens every tool call through the external BLACK_WALL forecast() service before it runs — returning GO / CAUTION / STOP, a risk score, named red flags, and an Ed25519-signed, offline-verifiable receipt.

  • observe mode (default): logs the verdict, never blocks — safe to trial.
  • enforce mode: STOP blocks; CAUTION blocks by default (this runtime has no interactive approval surface), carrying the red-flag detail in the block reason. Configurable via cautionAction.
  • Defense-in-depth against destructive commands, irreversible writes, exfiltration, or fund movement a compromised / prompt-injected agent might attempt — independent of the model's own judgment.

Contents

index.ts (plugin), openclaw.plugin.json (manifest), skills/blackwall-policy + skills/blackwall-verify, and index.test.ts — a Vitest suite covering the before_tool_call decision state machine, the HTTPS-only credential guard, and the proxy CONNECT-header size cap.

Context

This began as a nemoclaw-blueprint plugin PR on the main repo (NVIDIA/NemoClaw#4692). Per the maintainer's guidance there — that an independent third-party runtime integration belongs in nemoclaw-community rather than core — I've moved it here, as I offered on that PR. The code is unchanged from the version reviewed there (including the security fixes from that review). The README frames it clearly as an independent third-party integration calling an external service, not a NemoClaw-supported surface.

Signed-off-by: Samuel Trujillo bluetier.operations@gmail.com

Checks

  • DCO: commit is signed off.
  • License Headers: scripts/check_license_headers.py --check passes locally (.ts files carry SPDX headers).
  • No new dependencies; nothing added to THIRD-PARTY-NOTICES.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com

@bluetieroperations-create bluetieroperations-create mentioned this pull request Jul 14, 2026
Closed
6 tasks
@slopp

slopp commented Jul 19, 2026

Copy link
Copy Markdown
Collaborator

Thanks @bluetieroperations-create; apologies for the delay in review. Could you please add an entry in the top-level README table? Also left a few minor comments

slopp
slopp reviewed Jul 19, 2026
View reviewed changes
Comment thread examples/recipes/partners/bluetier/blackwall-guard/README.md
slopp
slopp reviewed Jul 19, 2026
View reviewed changes
Comment thread examples/blackwall-guard/README.md Outdated
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Jul 19, 2026
@bluetieroperations-create @claude
Address review: README table entry, support/pricing note, egress cred…
91ea883 
… injection

Per @slopp's review on NVIDIA#52:
- Add a BLACK_WALL Preflight Guardrail row to the top-level Reference Examples
  table.
- Disclose in the example README that it requires a BLACK_WALL API key (free
  tier, usage-based pricing above it) and that support is BlueTier Operations,
  not NVIDIA.
- Add an OpenShell provider (providers/blackwall.yaml, auth_style: bearer) and a
  sandbox network policy (policy.yaml) so the API key is injected at the L7 proxy
  on egress and never enters the sandbox, scoped to only the forecast endpoints
  the plugin calls. Mirrors the personal-community-sentiment-triage pattern and
  is documented as the recommended deployment. The plugin needs no change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Samuel Trujillo <270213615+bluetieroperations-create@users.noreply.github.com>
@bluetieroperations-create

bluetieroperations-create commented Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @slopp — addressed all three:

  • Top-level README table: added a BLACK_WALL Preflight Guardrail row to the Reference Examples table.
  • Support + key: the intro note now states it requires a BLACK_WALL API key (free tier, with usage-based pricing above it) and that support is provided by BlueTier Operations, not NVIDIA (contact + link included).
  • Credential injection at egress: great call — keeping the secret out of the agent's reach is Black_Wall's own thesis, so I've made it the recommended deployment. Added providers/blackwall.yaml (auth_style: bearer) + policy.yaml scoping egress to just POST /api/v1/forecast and .../outcome, mirroring the personal-community-sentiment-triage provider/policy pattern. BLACKWALL_API_KEY is only an OpenShell placeholder inside the sandbox; the L7 proxy injects the real key on egress, so it never enters the sandbox. The plugin needs no change. Happy to tweak the exact placeholder/injection wiring if your current OpenShell schema differs from the example I mirrored.

Appreciate the thorough review.

@apurvvkumaria apurvvkumaria mentioned this pull request Jul 29, 2026
Merged
23 tasks
@apurvvkumaria

apurvvkumaria commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Maintainer hold at exact head 1cee3c3351de2da2b2ea49e225ebda81ff69925d: security/privacy/business acceptance is required before conflict resolution or catalog migration.

This integration sends each tool-call payload and outcome metadata to a commercial third-party service and presents that service as a pre-action boundary while defaulting to observe/fail-open behavior. The credential-injection review thread remains unresolved, and the proposed provider/placeholder flow has not been proven against the current OpenShell schema. The contribution also lacks a complete install/start/teardown path. Please have the relevant owner approve the data-sharing, pricing/support, fail-open, and enforcement contract first. After that, prove credential injection live, add runnable lifecycle/tests, move it to the canonical catalog, resolve both review threads, and rerun current checks.

@bluetieroperations-create

bluetieroperations-create commented Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @bluetieroperations-create; apologies for the delay in review. Could you please add an entry in the top-level README table? Also left a few minor comments

Done — the root README's Reference Examples table now has a "BLACK_WALL Preflight Guardrail" row describing the pre-action gate, the provider-based key injection, and linking the example guide. Resolving.

Generated by Claude Code

@bluetieroperations-create

bluetieroperations-create commented Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @apurvvkumaria — the hold's characterization was fair, and rather than argue with it we changed the defaults so the objections no longer apply. Point-by-point, now at head 0377f5a:

1. Data sharing — tool-call payloads no longer leave the sandbox by default.
As of this head, forecasts default to inputMode: "metadata": the tool name plus a summary of its parameters — key names (clipped, max 50), value JSON types, and byte sizes. Parameter values are never transmitted in this mode — no commands, file contents, URLs, or tokens. Sending size-capped contents is now a per-deployment opt-in (inputMode: "contents"), and the README's new "What leaves the sandbox (data sharing)" section documents both modes precisely. The after_tool_call report carries only an outcome class and divergence severity, never tool output.

On the service side: the service is operated by BlueTier Operations LLC and hosted on Vercel. Request metadata is retained as part of the signed-receipt audit trail; what persists long-term is counterparty outcome records (keyed to the counterparty being scored, built from confirmed activity) — not profiles of the calling agent or its operator. Data is not sold or shared with third parties beyond the hosting infrastructure; deletion requests go to bluetier.operations@gmail.com.

2. Pre-action boundary vs observe/fail-open — the defaults now match the claim.
failClosed now defaults to true: in enforce mode, an unreachable gate blocks the action rather than letting it run unscored; fail-open is an explicit opt-out. The README no longer presents observe mode as a boundary — it is documented as a trial/rollout mode, with the recommended sandboxed profile being mode: enforce with defaults left on. The enforcement contract is pinned by the test suite (27 tests: observe/enforce × GO/CAUTION/STOP × caution-action × fail-closed).

3. Credential injection — probe added; live in-sandbox proof is the remaining step.
providers/blackwall.yaml keeps the key host-side with proxy injection at egress, and the new scripts/verify.sh includes a live three-way injection probe verified against the production API: HTTP 2xx = real key injected; 401 invalid_api_key = placeholder passed through unreplaced; 401 missing_api_key = no Authorization header arrived. What we have not yet done is run it inside a current-schema OpenShell sandbox — if you can point us at the current provider schema (or the sandbox the sentiment-triage example validates against), we'll run the probe there and post the output.

4. Install/start/teardown — complete and runnable.
scripts/install.sh / verify.sh / teardown.sh (teardown is manifest-id-guarded). Tests now run in-repo with no OpenClaw host: npm install && npm test.

5. Pricing/support. This integration is community-contributed and supported by BlueTier Operations, not NVIDIA (the README states this prominently): free API keys at blackwalltier.com, usage-based pricing above the free tier, support best-effort via bluetier.operations@gmail.com. There is no NVIDIA support obligation or SLA attached to this contribution.

6. Catalog migration. We're happy to move this to the canonical catalog once acceptance lands — please confirm the destination (brevdev/nemoclaw-demos, per the root README's convention for externally-hosted examples — or the reorganized in-repo catalog from #61?) and we'll open the PR there.

Both of @slopp's earlier review threads are now addressed and resolved at this head (table entry, support/paid-key callout, and the provider-based credential-injection flow). Could you route the data-sharing/pricing/fail-open contract above to the owner who needs to sign off on acceptance?

Generated by Claude Code

@apurvvkumaria apurvvkumaria added feature PR adds or expands user-visible functionality area: security Security controls, permissions, secrets, or hardening. area: integrations Third-party service integration behavior labels Aug 5, 2026
apurvvkumaria
apurvvkumaria requested changes Aug 5, 2026
View reviewed changes

@apurvvkumaria apurvvkumaria left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the detailed update. We want to help get this integration into a mergeable state, but the current head still needs changes before it can be accepted.

  1. Align the enforcement architecture with OpenShell. The current before_tool_call plugin runs inside the agent sandbox, so it is mutable by the agent and is not an independent security boundary. Please coordinate with the OpenShell maintainers on using the new Supervisor middleware where feasible. Because that middleware is still a research-preview integration and is not configured by standard NemoClaw onboarding, document the agreed design. If the in-sandbox plugin remains, describe it strictly as defense-in-depth and explain why Supervisor middleware is not suitable here.
  2. Provide a complete current NemoClaw/OpenShell lifecycle. The recipe must onboard or select the sandbox, import and create the provider, explicitly attach the provider to the sandbox, install and enable the integration in the sandbox, verify a real OpenClaw tool call is intercepted, and cleanly tear everything down. The current install script copies files to a host plugin directory and leaves the critical provider, policy, and enablement steps manual.
  3. Update the contribution to current main: resolve the merge conflict, move it to examples/recipes/partners/bluetier/blackwall-guard/, add it to examples/README.md, and remove links to the retired catalog/example layout.
  4. Add the contributor's valid Signed-off-by: line to the PR description so the current DCO workflow can attest the contribution after the branch is updated.

Once the OpenShell architecture is agreed with the partner, the maintainer team can help with the rebase, catalog migration, workflow wiring, and final validation. We are requesting changes rather than closing the PR because we want to work with BlueTier to land it in a safe, supportable form.

This was referenced Aug 5, 2026
Merged
Merged
@bluetieroperations-create @claude
Add blackwall-guard partner recipe: BLACK_WALL pre-action risk gate f…
0d22cb2 
…or OpenClaw agents

A community-contributed pre-action risk gate for OpenClaw agents under
NemoClaw, at examples/recipes/partners/bluetier/blackwall-guard/ with a
BlueTier row in the Partner Recipes catalog.

- before_tool_call hook screens every tool call through the external
  BLACK_WALL forecast service (GO / CAUTION / STOP + signed receipts);
  documented strictly as defense-in-depth -- the independent layers are the
  OpenShell network policy and gateway-side credential injection, with
  Supervisor middleware documented as the intended independent boundary
  pending coordination.
- Data minimization by default: forecasts carry tool name + parameter key
  names/types/sizes only (inputMode "metadata"); sending size-capped
  contents is per-deployment opt-in. failClosed defaults to true.
- OpenShell provider profile + policy keep the API key out of the sandbox:
  the L7 proxy injects the credential at egress; a placeholder is all the
  sandbox ever holds.
- Complete lifecycle on the current command surface: scripts/bring-up.sh
  (profile import, provider create with gateway-held key, sandbox create
  with policy and provider attached), scripts/verify.sh (unit tests,
  egress, three-way credential-injection probe, real tool-call interception
  check), scripts/tear-down.sh (dependency-ordered teardown). Host-side
  dev loop kept as explicit install.sh/uninstall.sh.
- 27 vitest tests runnable in-repo (npm install, npm test); SPDX headers
  throughout.

Squash of the add-blackwall-guard-example branch history onto current main.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Re7K1cxTDh28mRCQ4xoiFu
@bluetieroperations-create

bluetieroperations-create commented Aug 5, 2026

Copy link
Copy Markdown
Contributor Author

Thanks — all four items are addressed, now as a single verified commit rebased onto current main (0d22cb2): moved to examples/recipes/partners/bluetier/blackwall-guard/ with the Partner Recipes catalog entry, a complete bring-up/verify/tear-down lifecycle on the current provider/policy/sandbox command surface (including an interception check for a real tool call), and the README documents the in-sandbox hook strictly as defense-in-depth with Supervisor middleware as the intended independent boundary. The DCO sign-off is in the PR description.

On item 1: we'd like to take you up on the coordination offer — who on the OpenShell side should we work with on the Supervisor integration, and is there a current provider-schema reference we should validate providers/blackwall.yaml against? Happy to iterate on the agreed design doc from there.

Generated by Claude Code

@bluetieroperations-create

bluetieroperations-create commented Aug 5, 2026

Copy link
Copy Markdown
Contributor Author

Note on the DCO check: the re-run replayed a pre-edit event snapshot — the sign-off is in the current description, and a fresh run (just triggered via description edit) picks it up.

Generated by Claude Code

bluetieroperations-create pushed a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 5, 2026
@claude
Migrate x402 payment gate to the partner catalog + lifecycle + review…
ddaa263 
…-hardening

Prepares the example for its upstream PR with every lesson from the
blackwall-guard (NVIDIA#52) review applied up front:

- Rebased content onto current main (post-NVIDIA#61 catalog); moved to
  examples/recipes/partners/bluetier/x402-payment-gate/ per the taxonomy
  (outcome-named, contributor supplied by the path) and registered in the
  Partner Recipes table.
- Enforcement architecture stated precisely: the before_tool_call hook
  cannot be skipped by prompting, but it runs inside the sandbox and is
  defense-in-depth, NOT an independent boundary; the untouchable layers are
  the OpenShell network policy and the absence of any in-sandbox credential
  (keyless). Supervisor middleware named as the independent-boundary
  evolution.
- Third-party support callout: contributed and supported by BlueTier
  Operations, not NVIDIA; default endpoint keyless and free.
- Complete lifecycle: scripts/bring-up.sh (sandbox + policy; no provider
  step exists because there is no credential), scripts/verify.sh (live
  4-scenario verdict walkthrough + 38 plugin unit tests + real tool-call
  interception check via the hook's deterministic gate line),
  scripts/tear-down.sh.
- Fixed retired-layout links and stale paths; demo re-verified live at the
  new location (4/4 scenarios).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Re7K1cxTDh28mRCQ4xoiFu
Signed-off-by: Claude <noreply@anthropic.com>
@bluetieroperations-create bluetieroperations-create mentioned this pull request Aug 6, 2026
Merged
8 tasks
bluetieroperations-create pushed a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 6, 2026
@claude
x402-payment-gate: maker/checker rework answering the full PR NVIDIA#105
50fa7be 
 review

Restructures the recipe so the mandatory payment decision lives OUTSIDE the
agent sandbox, in the pattern of recipes/nvidia/payment-ops-hermes, and
resolves every blocker from the review (both comments, all seven inline
threads):

- Maker/checker boundary: the sandboxed Hermes agent can only screen
  payments and SUBMIT intents (host/release_gate.py, reached via a scoped
  host.openshell.internal route). The host-side gate runs the mandatory
  Blackwall verdict and only a GO is signed then settled -- genuinely
  pre-signature, on the UNSIGNED claim: no signature exists until after the
  verdict, and the signing step is reachable only from the release branch
  (pinned by unit test). HOLD requires a named human (X-Operator header);
  STOP is terminal; a verdict-service failure HOLDS (never fails open).
- Coherent single runtime: pure Hermes. The OpenClaw plugin is removed from
  this recipe (it remains canonical in the Blackwall repo and is contributed
  for OpenClaw runtimes in PR NVIDIA#52) -- which also removes the signed
  X-PAYMENT pass-through this recipe's data statement contradicted, the
  Node-process/binary-allowlist mismatch, and the vitest dependency +
  lockfile the compliance statement missed. All in-sandbox HTTP is python3
  or curl, exactly matching the policy binary allowlists.
- Complete sandbox policy: inference routes mirrored unbroadened from the
  chief-of-staff recipe + advisory verdict routes + intent-submission route.
  The rail (127.0.0.1:8780) has NO sandbox route -- the denied edge is the
  boundary, and verify tests it from inside the sandbox.
- Reproducible build: sandbox/Dockerfile from the pinned
  hermes-sandbox-base digest, baking the skill; bring-up.sh builds it and
  degrades gracefully (host boundary still comes up without docker or
  openshell).
- Fresh, uniquely identifiable verification: verify.sh initiates NEW
  payments each run through the gate against the live verdict service --
  released/refused/held canaries, rail ledger must grow by exactly the
  released one, and the settlement tx returned by THIS run's submission
  must be on the ledger. No log-pattern matching.
- host/test_release_gate.py: 14 stdlib unit tests with mutation notes
  (verdict mapping, verdict-then-sign order invariant, human-approval
  rules, intent validation). Full lifecycle dress-rehearsed live:
  verify: OK.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Re7K1cxTDh28mRCQ4xoiFu
Signed-off-by: Claude <noreply@anthropic.com>
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 6, 2026
@bluetieroperations-create @claude
refactor(x402-payment-gate): maker/checker boundary — mandatory decis…
14f06ba 
…ion outside the sandbox

Answers the full PR NVIDIA#105 review (both comments, all seven inline threads)
by restructuring the recipe in the pattern of recipes/nvidia/
payment-ops-hermes:

- The sandboxed Hermes agent (MAKER) can only screen payments and submit
  intents via a scoped host.openshell.internal route. The host-side
  release gate (CHECKER, host/release_gate.py) runs the mandatory
  Blackwall verdict on the UNSIGNED claim and only a GO is signed then
  settled -- genuinely pre-signature: the signing step is reachable only
  from the release branch, pinned by unit test. HOLD requires a named
  human (X-Operator); STOP is terminal; verdict-service failure HOLDS.
- Coherent single runtime (pure Hermes): the OpenClaw plugin is removed
  from this recipe -- it remains canonical in the Blackwall repository and
  is contributed for OpenClaw runtimes in PR NVIDIA#52. This also removes the
  signed X-PAYMENT pass-through, the Node/binary-allowlist mismatch, and
  the vitest dependency + lockfile the compliance statement missed. All
  in-sandbox HTTP is python3 or curl, matching the policy allowlists.
- Complete sandbox policy: chief-of-staff inference routes unbroadened +
  advisory verdict routes + intent route. The rail has NO sandbox route;
  verify.sh tests the denied edge from inside the sandbox.
- Reproducible build: sandbox/Dockerfile from the pinned
  hermes-sandbox-base digest; bring-up.sh builds it and degrades
  gracefully without docker/openshell.
- Fresh, uniquely identifiable verification: each run initiates new
  payments through the gate (released/refused/held), asserts the rail
  ledger grew by exactly the released one, and asserts the settlement tx
  returned by THIS run's submission is on the ledger. 14 stdlib unit
  tests; full lifecycle dress-rehearsed live (verify: OK).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Re7K1cxTDh28mRCQ4xoiFu
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 6, 2026
@bluetieroperations-create @claude
feat(examples): add x402-payment-gate partner recipe (BlueTier)
4a0c38a 
A maker/checker payment boundary for x402 machine payments, at
examples/recipes/partners/bluetier/x402-payment-gate/, in the pattern of
recipes/nvidia/payment-ops-hermes.

The sandboxed Hermes agent (MAKER) can only screen payments and submit
payment intents over a scoped host.openshell.internal route. A host-side
release gate outside the sandbox (CHECKER) runs the mandatory Blackwall
verdict on the UNSIGNED claim and only a GO is signed then settled --
genuinely pre-signature: the signing step is reachable only from the release
branch, pinned by unit test. HOLD requires a named human plus a host-only
approval token (printed to the gate's host log; the sandbox cannot read it),
and approval RE-SCREENS -- a fresh STOP refuses even a named human. STOP is
terminal; a verdict-service failure holds; the held->releasing transition is
lock-guarded against concurrent double-release, and intent submission is
capacity-bounded atomically.

Keyless by design: the default endpoint is the free public Blackwall
instance, no API key exists anywhere, and only the payment claim
(counterparty, amount, asset, chain, resource) ever leaves the sandbox --
never tool payloads, never keys. Single coherent runtime (Hermes); the
OpenClaw plugin lives in the Blackwall repo and is contributed separately in
PR NVIDIA#52.

The rail has NO sandbox route -- the denied edge is the boundary. The gate
binds a host interface the sandbox reaches (RELEASE_GATE_BIND, default
0.0.0.0); the rail stays 127.0.0.1. Complete sandbox policy (chief-of-staff
inference routes unbroadened + advisory verdict + intent route); reproducible
sandbox/Dockerfile from the pinned hermes-sandbox-base digest; bring-up /
verify / tear-down lifecycle. verify.sh initiates fresh payments each run
(released/refused/held canaries, unique-tx ledger assertion) and exercises
the in-sandbox maker path + denied edge -- and never reports a full pass when
that boundary stage was skipped. Host decision core has stdlib unit tests
(verdict mapping, verdict-then-sign order, human-approval re-screen,
double-release and capacity locks deterministically mutation-guarded).

Signed-off-by: Samuel Trujillo <bluetier.operations@gmail.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Re7K1cxTDh28mRCQ4xoiFu
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 6, 2026
@bluetieroperations-create @claude
feat(examples): add x402-payment-gate partner recipe (BlueTier)
a781d14 
A maker/checker payment boundary for x402 machine payments, at
examples/recipes/partners/bluetier/x402-payment-gate/, in the pattern of
recipes/nvidia/payment-ops-hermes.

The sandboxed Hermes agent (MAKER) can only screen payments and submit
payment intents over a scoped host.openshell.internal route. A host-side
release gate outside the sandbox (CHECKER) runs the mandatory Blackwall
verdict on the UNSIGNED claim. A payment reaches sign-then-settle through
exactly two host-side authorization paths, never any other way: automated
release settles unattended ONLY on a fresh GO; human-approved release is a
separate path for a HELD intent (a named human plus a host-only approval
token printed to the gate's host log, which the sandbox cannot read) that
RE-SCREENS with a fresh verdict first -- a fresh STOP refuses even a named
human. Both paths decide before any signature exists (the signing step is
reachable only from the release branch, pinned by unit test), so the decision
is genuinely pre-signature. STOP is terminal on both paths; a verdict-service
failure holds; the held->releasing transition is lock-guarded against
concurrent double-release, and intent submission is capacity-bounded
atomically.

Keyless by design: the default endpoint is the free public Blackwall
instance, no API key exists anywhere, and only the payment claim
(counterparty, amount, asset, chain, resource) ever leaves the sandbox --
never tool payloads, never keys. Single coherent runtime (Hermes); the
OpenClaw plugin lives in the Blackwall repo and is contributed separately in
PR NVIDIA#52.

The rail has NO sandbox route -- the denied edge is the boundary. The gate
runs two listeners with different exposure: a sandbox-facing SUBMIT/status
listener (RELEASE_GATE_BIND, default 127.0.0.1 -- SAFE, never promiscuous;
reaching the sandbox is an explicit opt-in to a specific host-internal bridge
interface) and a host-only APPROVE listener pinned to 127.0.0.1:8791 that the
sandbox has no route to. Splitting them means exposing the submit interface
never exposes /approve. The rail stays 127.0.0.1. Complete sandbox policy
(chief-of-staff inference routes unbroadened + advisory verdict + intent
route); reproducible sandbox/Dockerfile from the pinned hermes-sandbox-base
digest; bring-up / verify / tear-down lifecycle (openshell sandbox create
--from). The security boundary needs the created sandbox + its policy, not a
running agent runtime: verify.sh exercises the denied edge and the in-sandbox
maker path via sandbox exec, initiates fresh payments each run
(released/refused/held canaries, unique-tx ledger assertion), and never
reports a full pass when that boundary stage was skipped (a host-only run is
an explicit VERIFY_HOST_ONLY=1 opt-in with a distinct result). Host decision
core has stdlib unit tests (verdict mapping, verdict-then-sign order, the
two-path authorization contract and human-approval re-screen, double-release
and capacity locks deterministically mutation-guarded).

Signed-off-by: Samuel Trujillo <bluetier.operations@gmail.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 7, 2026
@bluetieroperations-create @claude
feat(examples): add x402-payment-gate partner recipe (BlueTier)
ce8f206 
A maker/checker payment boundary for x402 machine payments, at
examples/recipes/partners/bluetier/x402-payment-gate/, in the pattern of
recipes/nvidia/payment-ops-hermes.

The sandboxed Hermes agent (MAKER) can only screen payments and submit
payment intents over a scoped host.openshell.internal route. A host-side
release gate outside the sandbox (CHECKER) runs the mandatory Blackwall
verdict on the UNSIGNED claim. A payment reaches sign-then-settle through
exactly two host-side authorization paths, never any other way: automated
release settles unattended ONLY on a fresh GO; human-approved release is a
separate path for a HELD intent (a named human plus a host-only approval
token printed to the gate's host log, which the sandbox cannot read) that
RE-SCREENS with a fresh verdict first -- a fresh STOP refuses even a named
human. Both paths decide before any signature exists (the signing step is
reachable only from the release branch, pinned by unit test), so the decision
is genuinely pre-signature. STOP is terminal on both paths; a verdict-service
failure holds; the held->releasing transition is lock-guarded against
concurrent double-release, and intent submission is capacity-bounded
atomically.

Keyless by design: the default endpoint is the free public Blackwall
instance, no API key exists anywhere, and only the payment claim
(counterparty, amount, asset, chain, resource) ever leaves the sandbox --
never tool payloads, never keys. Single coherent runtime (Hermes); the
OpenClaw plugin lives in the Blackwall repo and is contributed separately in
PR NVIDIA#52.

The rail has NO sandbox route -- the denied edge is the boundary. The gate
runs two listeners: a sandbox-facing SUBMIT/status listener and a host-only
APPROVE listener on 127.0.0.1:8791 the sandbox has no route to. The sandbox
reaches the host over the OpenShell bridge (host.openshell.internal -> the
openshell-docker network gateway), not host loopback, so bring-up discovers
that bridge gateway and binds the submit listener there -- reachable by the
sandbox and the host, but not the LAN (never 0.0.0.0). The rail stays on
loopback. Complete sandbox policy (chief-of-staff inference routes unbroadened
+ advisory verdict + intent route); reproducible Dockerfile built with the
recipe root as context (openshell sandbox create --from <recipe-root>, a
.dockerignore trims the context); bring-up / verify / tear-down lifecycle.

Validated end to end on a live OpenShell + Docker host: bring-up builds the
image and reaches Ready, the in-sandbox maker path submits over the scoped
route and gets a fresh verdict, and the rail is refused from the sandbox by
policy (the denied edge holds). verify.sh initiates fresh payments each run
(released/refused/held canaries, unique-tx ledger assertion), judges the
denied edge by response content (OpenShell enforces egress at L7, so a denied
route returns HTTP 403 and curl exits 0 -- an exit-code check would misread
it), and never reports a full pass when the in-sandbox boundary stage was
skipped. Host decision core has 27 stdlib unit tests (verdict mapping,
verdict-then-sign order, the two-path authorization contract and human-approval
re-screen, double-release and capacity locks deterministically mutation-guarded).

Signed-off-by: Samuel Trujillo <bluetier.operations@gmail.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 7, 2026
@bluetieroperations-create @claude
feat(examples): add x402-payment-gate partner recipe (BlueTier)
71ce4d0 
A maker/checker payment boundary for x402 machine payments, at
examples/recipes/partners/bluetier/x402-payment-gate/, in the pattern of
recipes/nvidia/payment-ops-hermes.

The sandboxed Hermes agent (MAKER) can only screen payments and submit
payment intents over a scoped host.openshell.internal route. A host-side
release gate outside the sandbox (CHECKER) runs the mandatory Blackwall
verdict on the UNSIGNED claim. A payment reaches sign-then-settle through
exactly two host-side authorization paths, never any other way: automated
release settles unattended ONLY on a fresh GO; human-approved release is a
separate path for a HELD intent (a named human plus a host-only approval
token printed to the gate's host log, which the sandbox cannot read) that
RE-SCREENS with a fresh verdict first -- a fresh STOP refuses even a named
human. Both paths decide before any signature exists (the signing step is
reachable only from the release branch, pinned by unit test), so the decision
is genuinely pre-signature. STOP is terminal on both paths; a verdict-service
failure holds; the held->releasing transition is lock-guarded against
concurrent double-release, and intent submission is capacity-bounded
atomically.

Keyless by design: the default endpoint is the free public Blackwall
instance, no API key exists anywhere, and only the payment claim
(counterparty, amount, asset, chain, resource) ever leaves the sandbox --
never tool payloads, never keys. Single coherent runtime (Hermes); the
OpenClaw plugin lives in the Blackwall repo and is contributed separately in
PR NVIDIA#52.

The rail has NO sandbox route -- the denied edge is the boundary. The gate
runs two listeners: a sandbox-facing SUBMIT/status listener and a host-only
APPROVE listener on 127.0.0.1:8791 the sandbox has no route to. The sandbox
reaches the host over the OpenShell bridge (host.openshell.internal -> the
openshell-docker network gateway), not host loopback, so bring-up discovers
that bridge gateway and binds the submit listener there -- reachable by the
sandbox and the host, but not the LAN (never 0.0.0.0). The rail stays on
loopback. Complete sandbox policy (chief-of-staff inference routes unbroadened
+ advisory verdict + intent route); reproducible Dockerfile built with the
recipe root as context (openshell sandbox create --from <recipe-root>, a
.dockerignore trims the context); bring-up / verify / tear-down lifecycle.

Validated end to end on a live OpenShell + Docker host -- the full bring-up ->
verify -> tear-down lifecycle: bring-up builds the image and reaches Ready
(exit 0), the in-sandbox maker path submits over the scoped route and gets a
fresh verdict, the rail is refused from the sandbox by policy (the denied edge
holds), and tear-down stops the services and deletes the sandbox. verify.sh
initiates fresh payments each run (released/refused/held canaries, unique-tx
ledger assertion), judges the denied edge by response content (OpenShell
enforces egress at L7, so a denied route returns HTTP 403 and curl exits 0 --
an exit-code check would misread it), and never reports a full pass when the
in-sandbox boundary stage was skipped. Host decision core has 27 stdlib unit
tests (verdict mapping, verdict-then-sign order, the two-path authorization
contract and human-approval re-screen, double-release and capacity locks
deterministically mutation-guarded).

Signed-off-by: Samuel Trujillo <bluetier.operations@gmail.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
bluetieroperations-create added a commit to bluetieroperations-create/nemoclaw-community that referenced this pull request Aug 7, 2026
@bluetieroperations-create @claude
feat(examples): add x402-payment-gate partner recipe (BlueTier)
4a15dfd 
A maker/checker payment BOUNDARY for x402 machine payments, at
examples/recipes/partners/bluetier/x402-payment-gate/, in the pattern of
recipes/nvidia/payment-ops-hermes.

Scope: this recipe demonstrates the host-side payment boundary, not a full
agent runtime. bring-up.sh stands up the boundary (mock rail + release gate +
a policy-scoped sandbox) and verify.sh exercises the in-sandbox maker path at
the intent-submission level (POST /v1/intents over the scoped
host.openshell.internal route -> a live verdict) plus the denied edge. It does
NOT start an interactive Hermes agent; the skill under agents/hermes/skills/
documents how a Hermes agent would drive this boundary, and running that agent
needs a full NemoClaw Relay+Hermes runtime (a separate operator step).

The sandboxed agent (MAKER) can only submit payment intents. A host-side
release gate outside the sandbox (CHECKER) runs the mandatory Blackwall verdict
on the UNSIGNED claim. A payment reaches sign-then-settle through exactly two
host-side authorization paths, never any other way: automated release settles
unattended ONLY on a fresh GO; human-approved release is a separate path for a
HELD intent (a named human plus a host-only approval token the sandbox cannot
read) that RE-SCREENS with a fresh verdict first -- a fresh STOP refuses even a
named human. Both paths decide before any signature exists (pinned by unit
test). STOP is terminal on both; a verdict-service failure holds; the
held->releasing transition is lock-guarded against concurrent double-release,
and intent submission is capacity-bounded atomically.

Keyless by design: the default endpoint is the free public Blackwall instance,
no API key exists anywhere, and only the payment claim (counterparty, amount,
asset, chain, resource) ever leaves the sandbox. Single coherent runtime
(Hermes); the OpenClaw plugin lives in the Blackwall repo and is contributed
separately in PR NVIDIA#52.

The rail has NO sandbox route -- the denied edge is the boundary. The gate runs
two listeners: a sandbox-facing SUBMIT listener and a host-only APPROVE listener
(127.0.0.1:8791). The sandbox reaches the host over the OpenShell bridge
(host.openshell.internal -> the openshell-docker network gateway), not loopback,
so bring-up discovers that bridge gateway and binds the submit listener there --
reachable by the sandbox and the host, but not the LAN (never 0.0.0.0). The rail
stays on loopback. Reproducible Dockerfile built with the recipe root as context
(openshell sandbox create --from <recipe-root>, a .dockerignore trims it);
bring-up always rebuilds the sandbox from the current checkout (never reuses a
possibly-stale one). bring-up / verify / tear-down lifecycle.

Enforcement architecture: the mandatory decision runs in the host-side release
gate (the payment-ops-hermes pattern). Wiring the same verdict into OpenShell
Supervisor middleware is the ideal fail-closed tightening and the documented
next step, offered for explicit maintainer agreement rather than silently
substituted.

Validated end to end on a live OpenShell + Docker host (bring-up -> verify ->
tear-down, plus a rebuild-over-existing run): bring-up reaches Ready, the
in-sandbox maker path submits over the scoped route and gets a fresh verdict,
and the rail is refused from the sandbox as HTTP 403 policy_denied -- the denied
edge, asserted positively (a timeout, DNS failure, or connection refusal fails
rather than passing). Host decision core has 27 stdlib unit tests (verdict
mapping, verdict-then-sign order, the two-path authorization contract and
human-approval re-screen, double-release and capacity locks deterministically
mutation-guarded).

Signed-off-by: Samuel Trujillo <bluetier.operations@gmail.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
apurvvkumaria pushed a commit that referenced this pull request Aug 7, 2026
@bluetieroperations-create @claude
feat(examples): add x402-payment-gate partner recipe (BlueTier) (#105)
e36ae2d 
## Related Issue

Companion to #52 (blackwall-guard) — same contributor, complementary
scope. No issue to close.

## Description

Adds a partner recipe at
`examples/recipes/partners/bluetier/x402-payment-gate/`: a maker/checker
payment **boundary** for [x402](https://www.x402.org/) machine payments,
in the pattern of `recipes/nvidia/payment-ops-hermes`. Before any x402
payment is signed, a host-side gate outside the sandbox asks a Blackwall
verdict service to score the claim — counterparty reputation on Base,
price-anomaly detection, OFAC sanctions screening, Sybil/graph signals —
pre-signature.

- **Scope — a boundary demonstration, not a full agent runtime.**
`bring-up.sh` stands up the boundary (rail + gate + policy-scoped
sandbox); `verify.sh` exercises the in-sandbox maker path at the
**intent-submission level** (`POST /v1/intents` over the scoped
`host.openshell.internal` route → live verdict) plus the denied edge. It
does **not** start an interactive Hermes agent — the skill under
`agents/hermes/skills/` documents how a Hermes agent *would* drive this
boundary; running that agent needs a full NemoClaw Relay+Hermes runtime
and is a separate operator step.
- **Keyless, minimal data sharing.** Default endpoint is the free public
instance; no API key exists anywhere. Only the payment claim
(`counterparty, amount, asset, chain, resource`) leaves the sandbox —
never tool payloads, never keys.
- **Maker/checker boundary.** The sandboxed agent (MAKER) can only
submit intents; a host-side release gate (CHECKER) runs the mandatory
verdict and is the only thing that signs and settles. The rail has
**no** sandbox route — that denied edge is the boundary. No plugin ships
here; the OpenClaw plugin lives in the Blackwall repo, contributed
separately in #52.
- **Two authorization paths.** Automated release settles only on a fresh
**GO**; human-approved release is a separate path for a HELD intent
(named human + a host-only approval token on `127.0.0.1:8791`) that
re-screens with a fresh verdict and still refuses a fresh **STOP**. Both
decide before any signature exists; STOP is terminal on both.
- **Split listeners, discovered bind.** The sandbox reaches the host
over the OpenShell bridge (`host.openshell.internal` → the
`openshell-docker` gateway), not loopback, so `bring-up.sh` **discovers
that bridge interface and binds the submit listener there** — reachable
by the sandbox and the host, not the LAN, never `0.0.0.0`. Rail and
approve stay on loopback.
- **Complete lifecycle.** `scripts/bring-up.sh` (`openshell sandbox
create --from <recipe-root>` — the Dockerfile lives at the recipe root
so its build context matches its `COPY` paths, `.dockerignore` trims it
— and **always rebuilds the sandbox from the current checkout**, never
reusing a stale one), `scripts/verify.sh` (live canaries + the
in-sandbox denied-edge test, which **positively requires HTTP `403
policy_denied`** and fails on transport errors), `scripts/tear-down.sh`.
- **Enforcement architecture.** The mandatory decision runs in the
host-side release gate (the `payment-ops-hermes` pattern). Wiring the
same verdict into OpenShell Supervisor middleware is the ideal
fail-closed tightening and the documented next step — offered for
explicit maintainer agreement, not silently substituted.
- Single verified commit on current `main`, registered in the Partner
Recipes catalog table. Note: #52 also adds a BlueTier row to that table
— whichever PR lands second needs a one-line rebase there.

## Verification

- [x] `python3 scripts/check_license_headers.py --check`
- [ ] `python3 scripts/check_label_taxonomy.py --check` when governance
metadata changes (n/a — no governance metadata changed)
- [x] `git diff --check`
- [x] Relevant example setup or syntax checks (`bash -n` on all
lifecycle scripts; host unit suite 27/27; **validated end to end on a
live OpenShell + Docker host** — bring-up → verify → tear-down, the
in-sandbox maker path returns a fresh verdict and the rail is refused as
HTTP 403 `policy_denied`)

## Release And Compliance

- [x] No secrets, local `.env` files, private certificates, snapshots,
or token caches are included.
- [x] Third-party dependency changes are reflected in
`THIRD-PARTY-NOTICES` (none added — stdlib Python only).
- [x] Public documentation is free of internal-only links or private
workspace details.
- [x] I added my DCO sign-off declaration to this pull request
description.

Signed-off-by: Samuel Trujillo <bluetier.operations@gmail.com>

---
_Generated by [Claude Code](https://claude.ai/code)_

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@slopp slopp slopp left review comments
@apurvvkumaria apurvvkumaria apurvvkumaria requested changes
@wscurran wscurran Awaiting requested review from wscurran wscurran is a code owner
@ericksoa ericksoa Awaiting requested review from ericksoa ericksoa is a code owner
@cv cv Awaiting requested review from cv cv is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

area: integrations Third-party service integration behavior area: security Security controls, permissions, secrets, or hardening. feature PR adds or expands user-visible functionality

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bluetieroperations-create @slopp @apurvvkumaria