NVIDIA OpenShell

NVIDIA OpenShell runs an AI agent in a sandbox: a restricted environment that controls which files and network services the agent can reach.

AuthRail adds a different check: may this agent perform this business action? For example, OpenShell can keep a support agent away from your payment credentials. AuthRail can require approval when that agent asks your application to issue a large refund.

This guide shows how the two connect. The agent sends a request to your application. Your application checks it with AuthRail before calling the tool.

How the parts fit

Agent in OpenShell → your protected application → business tool
                              ↕
                    AuthRail SDK and sidecar

Your protected application runs outside the sandbox. It holds the provider credentials and uses the Node SDK with a local AuthRail sidecar. The agent gets access to the application route, rather than the provider credential itself.

The integration covers the tools you connect through that application. Install it at the actual tool call; installing OpenShell alone does not add AuthRail checks to every command.

Before you start

You need a working Node integration, an Enforce deployment in AuthRail, and an OpenShell installation operated by your team. The example uses OpenShell 0.1.6 and Node 22.13 or newer. Follow the NVIDIA installation guide for the OpenShell setup.

The supplied example records a simulated amount in SQLite on your machine. Use it to check the connection before replacing its sample function with a real business tool.

1. Prepare the example application

Keep the Node SDK and sidecar repositories beside each other. From your authrail-sidecar checkout, run:

npm --prefix ../authrail-sdk-node ci
npm --prefix ../authrail-sdk-node run build
cd integrations/openshell
npm ci
cp operator-settings.example.json operator-settings.json

This example uses a sibling SDK checkout through its local package dependency. These commands build that checkout, install the example and make a settings file for you to fill in. Keep the settings and referenced secret files private. Reuse your existing checkouts if you followed the sidecar setup.

Open operator-settings.json. Add your AuthRail organisation, deployment and reviewed action IDs. Point it to the private key and token files from your connection setup. The example also needs an HTTPS certificate and its private key, plus a separate encryption key for saving recovery information. Its setup instructions explain those files and every settings field.

2. Allow the sandbox to reach your application

Review the supplied policy.yaml with the person operating OpenShell. Set the application's hostname, port and permitted executable. Allow the agent to call that application while keeping its credential files and the sidecar private.

The application uses HTTPS. Make sure OpenShell trusts its certificate and can reach it before trying a business request. Keep certificate verification on.

Save the sandbox details in operator-settings.json using the sandbox setup steps. The application checks that the intended sandbox is ready and still uses the reviewed policy before it accepts a protected request.

Network and policy details for the OpenShell operator

Use the exact sandbox ID and loaded policy revision, along with the gateway, workspace and policy digest. A digest identifies the reviewed policy content. Recreating a sandbox changes its ID even when its name is reused.

Keep OpenShell's required filesystem restrictions enabled. Review all effective rules, including provider-added rules. Keep direct provider access, the sidecar port, host sockets and application credential directories outside the agent's access.

The OpenShell network supervisor must trust the application's HTTPS certificate. Adding a private certificate authority only to the agent image is insufficient. For Docker placement, the protected application can share the sidecar's private network; expose only the application's HTTPS entry point. The integration guide covers certificate trust, Docker networking and policy inspection commands.

3. Start the application and try a request

From integrations/openshell, start the configured example:

node start.mjs ./example-config.mjs

From inside the sandbox, send an authenticated POST /execute request to the reviewed HTTPS application address with Content-Type: application/json and this body:

{"requestKey":"sample-invoice-001","arguments":{"amount":80}}

Use the sandbox's separate request token in the Authorization: Bearer … header. It is not the adapter token or a provider credential. The example request instructions show how this route authenticates the sandbox. Keep the request key when recovering the same business intent; a different key starts a different request.

Then open Actions & decisions in AuthRail. You should see the request check, the result check and the application's execution report. Compare an allowed amount with an amount your Rail denies. The denied request should leave no new sample effect.

Understand waiting and uncertain results

approval_required means the application saved the request for human review. Approval and resuming the request stay in the protected application; the agent cannot supply its own approval.

result_withheld means the result was stopped, but the tool may already have run. outcome_unknown means the application could not establish the effect. Check the original operation before retrying. See recovery.

A duplicate request is blocked instead of running a second effect. If the sandbox is stopped, its policy changes, or its state cannot be checked, new protected requests stop too. Restore and review the connection before retrying.

Keep the application journal, its encryption key, the sample ledger and the complete sidecar state across restarts. These hold the information needed to recover an interrupted request.

Check the boundary before using a real tool

From the actual sandbox, confirm that an allowed request works and a denied request cannot run the tool. Also confirm that the agent cannot read the application's credentials or reach the same provider directly. Follow the integration's boundary checklist when reviewing your own image, policy and business tool.