Skip to content

guides

Intended Documentation

OpenShell Operations Runbook

Operate a customer-run OpenShell / NemoClaw runtime governed by Intended — compile and apply policy, monitor decisions, roll back safely, and escalate incidents.

intermediate4 min readimplemented

OpenShell Operations Runbook#

Use this runbook to operate a customer-run OpenShell / NemoClaw runtime whose policy is compiled and governed by Intended. The runtime executes in your environment; Intended compiles the sandbox policy and records the audit trail. The boundary between the two is where this runbook focuses.

Where the responsibility boundary sits
The Intended control plane compiles policy and records audit on one side of the tenant boundary; the customer-operated runtime, its hosts, credentials, and egress sit on the other — the operator owns deployment and hardening, Intended owns authorization and audit.

Intended owns the authorization and audit boundary. The operator owns the runtime, its hosts, credentials, and egress.

Preconditions#

Before a rollout, confirm:

  • the runtime owner and an approver are identified;
  • a staging environment is available;
  • the rollback path is validated (you can reapply the last-known-good artifact);
  • the operator has reviewed the shared-responsibility boundary below.

Rollout sequence#

Compile the policy artifact

bash
intended openshell-compile \
  --input intended-openshell.json \
  --output intended-openshell.yaml

Capture the generated header (profile, risk_posture, inferred_presets) and the file hash in your change record.

Review the inferred scope

Confirm the inferred presets, endpoint hosts/methods, and binary access match what the runtime needs — and nothing more. Pay particular attention to any destination introduced by a runtime or provider baseline rather than your explicit requestedPresets.

Apply in staging, review-first

Apply with the upstream runtime interface and run review-first:

bash
openshell policy set intended-openshell.yaml

Keep high-risk capability paths in review mode for the first governed runs.

Validate decision-to-audit linkage

For the first governed runs, confirm each decision has a corresponding audit entry and that runtime correlation metadata is present. Stream decisions live while you exercise the runtime:

bash
intended watch --apikey "$INTENDED_API_KEY" --tenant "$INTENDED_TENANT_ID"
# narrow the stream:
intended watch --tenant "$INTENDED_TENANT_ID" --decision DENY --min-risk 60

Promote to production

Promote only after approver sign-off, with the artifact hash and change ticket recorded.

Production checks#

  • The policy artifact hash and change-ticket ID are recorded.
  • Audit records include runtime correlation metadata.
  • Fail-closed paths deny unapproved high-risk actions (a denied action returns no token, so the runtime cannot act).
  • The escalation flow works for blocked or denied actions.

Rollback protocol#

  1. Reapply the last-known-good policy artifact (openshell policy set <previous>.yaml).
  2. Switch runtime-sensitive capabilities back to review mode.
  3. Pause high-risk connector paths until the drift is resolved.
  4. Open an incident review and attach the decision and audit evidence (export with intended audit-export --tenant <id> --intent <intentId>).

Incident escalation#

Trigger an incident when:

  • policy drift is detected (applied policy diverges from the compiled artifact);
  • an unknown destination appears in egress;
  • an execution-to-audit mismatch occurs;
  • repeated DENY events indicate malformed runtime requests.

Include in the incident record:

  • the policy artifact hash;
  • the runtime environment;
  • the relevant decision / correlation IDs;
  • the impacted systems and current mitigation state.

Monitoring and evidence commands#

GoalCommand
Live decision streamintended watch --tenant <id> [--decision DENY] [--min-risk <n>]
Query audit entriesintended audit-query --tenant <id> [--correlation <id>] [--event-type <type>]
Export evidence for an intentintended audit-export --tenant <id> --intent <intentId>
Inspect a token's claimsintended inspect-token --token <jwt>

Evidence verification is HMAC with the tenant secret

An exported evidence bundle is integrity-protected with HMAC-SHA256 keyed off the tenant's own stored secret. Verifying it requires possession of that tenant secret — it is tamper-evident, but not publicly or asymmetrically verifiable. State this precisely when you share bundles externally.

Shared-responsibility reminder#

Intended governs the authorization and audit boundary: it compiles the policy, decides each action, and records tamper-evident evidence. Your team owns everything on the runtime side of the boundary — upstream runtime deployment, host hardening, credential handling, and provider-specific operational controls.

Next steps#

OpenShell Operations Runbook | Intended