Getting started on OpenShell

Enforce intent on an agent running in an NVIDIA OpenShell sandbox, with no change to the agent.

NVIDIA OpenShell is the surface available today. The ArmorIQ OpenShell middleware registers as supervisor middleware and is called before each sandbox request leaves, so an agent in an OpenShell sandbox is held to the plan its model issued. Nothing in OpenShell is modified, nothing is installed inside the sandbox, and the agent never learns it exists.

This surface enforces at the tool-call connection OpenShell already owns. The kernel checks on files, processes and local sockets arrive on the Linux and Docker surfaces, both in preview.

What it checks

OpenShell calls the service at PRE_CREDENTIALS, before credentials are injected, for every outbound request a sandbox makes. It answers allow or deny, and OpenShell enforces the answer.

CheckComes fromRefuses
Declared scopedeclared_tools, written once by whoever creates the sandboxA tool the sandbox was never set up to use
Captured planThe model's latest reply, with -capture-planA tool the model did not ask for
PolicyThe ArmorIQ control planeA tool the agent is not permitted to call

A call the model did not ask for is refused with intent_drift_from_plan before any policy is consulted. The reply is read before the sandbox receives it, so the plan is in place before the agent can act on it.

Before you start

  • OpenShell v0.1.2. Request-side checks work on earlier gateways with config version = 1; holding a sandbox to its model's plan needs v0.1.0 or later.
  • An ArmorIQ organization and an API key, from platform.armoriq.ai. Policies are authored in the same organization, so the key and the policies that govern your agents live together.
  • At least one policy. A new organization has no policies and the default is to block, so add one before your first run or every call is denied.

See it on one host first

The examples/intent-demo in the repo runs the whole thing on one Linux host, with a stand-in model and a scripted agent: the same call refused when the model did not ask for it, and allowed when it did.

1. Get the middleware

A prebuilt linux-amd64 binary ships in the repo. To build it yourself:

go build -o openshell-middleware ./cmd/openshell-middleware

A single static binary, no runtime dependencies.

2. Create an API key and a starter policy

Issue an API key in the dashboard. Then add a policy, since the default is to block. A minimal policy that exercises both decision paths, using two tool names as an example. Substitute tools your own agents actually call:

name: OpenShell trial
scope:
  target_type: org
default_action: block
rules:
  - tool: your_read_tool     # allowed, and declared by the sandbox below
    action: allow
  - tool: your_write_tool    # declared by the sandbox, but policy refuses it
    action: block

A third tool that the sandbox never declares at all shows the in-process refusal, without a policy being consulted.

3. Run the middleware

ARMORIQ_API_KEY=<key> ./openshell-middleware \
  -listen 0.0.0.0:50071 \
  -iap-url https://api.armoriq.ai \
  -timeout 2500ms

Add -capture-plan to hold each sandbox to its model's plan, on OpenShell v0.1.0 or later.

Start the middleware before the gateway. OpenShell refuses to start when a registered middleware is unavailable. The key is read from the environment, not a flag, because a flag is visible in ps to every user on the host.

4. Register it with the gateway

In your gateway config, normally ~/.config/openshell/gateway.toml:

[openshell]
version = 2

[[openshell.supervisor.middleware]]
name = "armoriq-intent"
grpc_endpoint = "http://172.17.0.1:50071"
allow_insecure_transport = true   # same host only; use TLS otherwise
max_payload_bytes = 262144
timeout = "3s"

OpenShell v0.1.0 and later require version = 2 and reject version = 1.

grpc_endpoint must be reachable from the gateway and from every sandbox supervisor. Supervisors run inside the container, so 127.0.0.1 there is the container's own loopback, not your host. On a single box the Docker bridge address works. This is the most common setup mistake: the deployment looks healthy while every request is denied with binding_not_described because the supervisor could not reach the service. Raise the timeout above the 500ms default; a policy decision takes roughly half a second, and the failure mode is closed.

5. Attach it to a sandbox

In the sandbox policy:

network_middlewares:
  armoriq:
    name: ArmorIQ intent enforcement
    middleware: armoriq-intent
    order: 10
    on_error: fail_closed
    config:
      agent_id: "<the agent this sandbox runs>"
      declared_tools: ["your_read_tool", "your_write_tool"]
      # model_hosts: ["api.openai.com"]  # with -capture-plan
      # require_captured_plan: true      # only with -capture-plan
    endpoints:
      include: ["mcp.example.internal"]

config is delivered to the middleware on every request, so identity and the declared tool set travel with the sandbox. Apply it with sandbox create --policy. Keep on_error: fail_closed.

What the workload sees

Only a short reason code reaches the requester. Everything else stays in the logs.

CodeMeaning
intent_blocked_by_policyA policy refused it.
tool_not_in_planNot among the tools the sandbox declared.
intent_drift_from_planNot asked for by the model's latest reply, with -capture-plan.
intent_awaiting_approvalThe decision needs a human; the call does not proceed.
intent_action_not_namedNo tool could be identified in the request.
intent_verification_failedNo decision could be obtained, so the request is denied.

Where to go next

On this page