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.
| Check | Comes from | Refuses |
|---|---|---|
| Declared scope | declared_tools, written once by whoever creates the sandbox | A tool the sandbox was never set up to use |
| Captured plan | The model's latest reply, with -capture-plan | A tool the model did not ask for |
| Policy | The ArmorIQ control plane | A 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-middlewareA 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: blockA 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 2500msAdd -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.
| Code | Meaning |
|---|---|
intent_blocked_by_policy | A policy refused it. |
tool_not_in_plan | Not among the tools the sandbox declared. |
intent_drift_from_plan | Not asked for by the model's latest reply, with -capture-plan. |
intent_awaiting_approval | The decision needs a human; the call does not proceed. |
intent_action_not_named | No tool could be identified in the request. |
intent_verification_failed | No decision could be obtained, so the request is denied. |
Where to go next
- The Linux and Docker surfaces add kernel checks on files, processes and local sockets through KAP, both in preview.
- Request preview access, or ask about a platform not listed, on the Intent Container product page.
- The Intent Containers series explains the design in five parts.