Skip to content

guides

Intended Documentation

OpenShell Runtime Quickstart

Compile a sandbox policy YAML for an OpenShell / OpenClaw / NemoClaw runtime from Intended presets, review the inferred scope, and apply it upstream.

beginner5 min readimplemented

OpenShell Runtime Quickstart#

OpenShell is a sandboxing layer for shell-style agent runtimes (OpenClaw, Claude Code, Codex CLI, and NemoClaw-style robotics runtimes). Intended's openshell-compile command turns a small declarative input into a complete OpenShell policy YAML — a filesystem sandbox plus a per-destination network allowlist — that you apply to the runtime. The policy is generated deterministically from presets, so you review exactly what egress and binary access the runtime gets before it runs.

This is the shortest safe path from nothing to an applied policy.

What the compiler produces#

openshell-compile emits a version: 1 OpenShell policy with:

  • a filesystem policy — read-only and read-write path sets plus a Landlock compatibility mode;
  • a process identity (run_as_user / run_as_group);
  • network policies — one entry per inferred preset, each listing allowed hosts, ports, HTTP methods, and binaries;
  • an optional geofences array for physical runtimes;
  • a risk posture of baseline or strict, inferred from your input.

Steps#

Write an input file

The input selects a runtime, optional providers, and the requestedPresets you want allowed. Save it as intended-openshell.json.

json
{
  "profileName": "intended-openshell",
  "runtime": "openclaw",
  "providers": ["nvidia"],
  "requestedPresets": ["github"]
}
  • runtime — one of generic, openclaw, claude-code, codex-cli. Each runtime contributes its own baseline presets (for example, openclaw pulls in clawhub, openclaw_api, openclaw_docs, and npm_registry).
  • providers — nvidia and/or anthropic. Providers add their inference-endpoint presets (nvidia → nvidia; anthropic → claude_code).
  • requestedPresets — explicit presets to allow. Available presets: claude_code, nvidia, github, clawhub, openclaw_api, openclaw_docs, npm_registry, telegram, discord, jira, slack, pypi, docker_hub.

The final policy is the union of runtime, provider, and requested presets, de-duplicated and sorted.

Compile the policy YAML

Run the compiler. Flags override or merge with the file: --runtime, --provider/--providers, --preset/--presets, and --profile.

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

Without --output, the YAML is printed to stdout — useful for piping into review. The generated file begins with a comment header recording the profile, risk posture, and inferred presets:

yaml
# Generated by INTENDED OpenShell Adapter
# profile: intended-openshell
# risk_posture: baseline
# inferred_presets: clawhub, github, npm_registry, nvidia, openclaw_api, openclaw_docs
# oiActions: none
# lim_archetypes: none
version: 1
filesystem_policy:
  include_workdir: true
  read_only: [/app, /dev/urandom, /etc, /lib, /proc, /sandbox/.openclaw, /usr, /var/log]
  read_write: [/dev/null, /sandbox, /sandbox/.openclaw-data, /tmp]
  landlock:
    compatibility: best_effort
process:
  run_as_user: sandbox
  run_as_group: sandbox
network_policies:
  github:
    endpoints:
      - host: api.github.com
        port: 443
        enforcement: enforce
        rules:
          - allow: { method: GET,  path: /** }
          - allow: { method: POST, path: /** }
        # …
    binaries:
      - { path: /usr/bin/gh }
      - { path: /usr/bin/git }
  # … one entry per inferred preset
geofences: []

Review the inferred scope

Before applying anything, read the generated file and confirm:

  • the inferred_presets header lists exactly the destinations you expect — nothing extra;
  • each network_policies entry's hosts, methods, and binaries match what the runtime actually needs;
  • the risk_posture is what you intend (see below);
  • no privileged or production-sensitive destination slipped in via a runtime/provider baseline.

Apply it upstream

Hand the YAML to the OpenShell runtime using its own interface:

bash
openshell policy set intended-openshell.yaml

openshell here is the upstream runtime CLI, not part of the Intended CLI. Intended compiles and governs the policy; applying it is the runtime's responsibility.

Validate in staging

  • Run the governed runtime in staging first.
  • Confirm in-scope actions succeed and out-of-scope egress is blocked.
  • Preserve the generated YAML (and its header hash) in your deployment records for audit.

Risk posture: baseline vs strict#

The compiler infers strict posture (and narrows allowed HTTP methods to just what your intents imply) when any supplied intent or LIM evaluation signals elevated risk — touchesProduction, requiresPrivilegedAccess, containsSensitiveData, a high/critical level, a fail-closed trigger, or conflicting signals. Otherwise it stays baseline with the preset's default methods. With a presets-only input (no intents), posture is baseline.

Advanced: driving scope from intents

The input also accepts intents (an array of Universal Intents) and limEvaluations. When present, the compiler infers additional presets from the intent's target system and verb, narrows methods under strict posture, and records the actions in the YAML header. This is optional — the presets-only form above compiles deterministically on its own. For physical runtimes, you can also supply a geofences array; geofence enforcement on the robot is part of the NemoClaw runtime and is Roadmap in this repo.

Shared responsibility#

Intended governs the authorization boundary and produces the policy artifact. You remain responsible for upstream runtime deployment, credential handling, destination review, and environment-specific hardening.

Next steps#

OpenShell Runtime Quickstart | Intended