NVIDIA OpenShell

https://docs.nvidia.com/openshell
Admin
NVIDIA OpenShell is an open-source runtime for executing autonomous AI agents in sandboxed...
Tokens:74,220
Snippets:1,081
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install OpenShell CLI

Source: https://docs.nvidia.com/openshell/about/installation.md

Executes the installation script to detect the OS, install the CLI and gateway, and start the local gateway server.

```shell
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

--------------------------------

### Install and Initialize OpenShell

Source: https://docs.nvidia.com/openshell/home

Use these commands to install the OpenShell runtime and initialize a new sandbox environment for an agent.

```shell
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell sandbox create -- claude
```

--------------------------------

### Install OpenShell via Snap

Source: https://docs.nvidia.com/openshell/about/installation.md

Installs the OpenShell package from the Snap Store.

```shell
sudo snap install openshell
```

--------------------------------

### Start llmster Daemon and Server

Source: https://docs.nvidia.com/openshell/get-started/tutorials/local-inference-lmstudio.md

Commands to initialize the daemon and start the server with network binding.

```shell
lms daemon up
```

```shell
lms server start --bind 0.0.0.0
```

--------------------------------

### Install local snap package

Source: https://docs.nvidia.com/openshell/about/installation.md

Installs a local .snap file and manually connects all required plugs for full functionality.

```shell
sudo snap install ./openshell_*.snap --dangerous
sudo snap connect openshell:home
sudo snap connect openshell:network
sudo snap connect openshell:network-bind
sudo snap connect openshell:docker docker:docker-daemon
sudo snap connect openshell:log-observe
sudo snap connect openshell:system-observe
```

--------------------------------

### Install OpenShell CLI

Source: https://docs.nvidia.com/openshell/get-started/quickstart.md

Install the CLI using the provided shell script or the uv package manager.

```shell
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

```shell
uv tool install -U openshell
```

--------------------------------

### Start Gateway Container

Source: https://docs.nvidia.com/openshell/about/container-gateway.md

Starts the gateway container with necessary volume mounts and environment variables.

```shell
docker run -d \
  --name openshell-gateway \
  --restart unless-stopped \
  --group-add docker \
  -p 127.0.0.1:8080:8080 \
  -v openshell-state:/var/openshell \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/openshell/supervisor/openshell-sandbox:~/openshell/supervisor/openshell-sandbox:ro \
  -e OPENSHELL_DRIVERS=docker \
  -e OPENSHELL_GRPC_ENDPOINT=http://host.openshell.internal:8080 \
  -e OPENSHELL_DOCKER_SUPERVISOR_BIN=~/openshell/supervisor/openshell-sandbox \
  -e OPENSHELL_DB_URL=sqlite:/var/openshell/openshell.db \
  -e OPENSHELL_DISABLE_TLS=true \
  ghcr.io/nvidia/openshell/gateway:latest
```

--------------------------------

### Network and HTTP Event Examples

Source: https://docs.nvidia.com/openshell/observability/logging.md

Examples of network and HTTP request logging.

```text
OCSF NET:OPEN [INFO] ALLOWED /usr/bin/curl(58) -> api.github.com:443 [policy:github_api engine:opa]
```

```text
OCSF HTTP:POST [MED] DENIED POST http://api.github.com/user/repos [policy:github_api engine:opa]
```

```text
OCSF NET:OPEN [MED] DENIED /usr/bin/curl(64) -> httpbin.org:443 [policy:- engine:opa] [reason:no matching policy]
```

```text
OCSF NET:OPEN [MED] DENIED /usr/bin/curl(1618) -> 169.254.169.254:80 [policy:- engine:ssrf] [reason:resolves to always-blocked address]
```

```text
OCSF HTTP:GET [INFO] ALLOWED GET http://api.internal.corp:8080/v1/status [policy:internal_api engine:opa]
```

--------------------------------

### Create a sandbox environment

Source: https://docs.nvidia.com/openshell/get-started/tutorials/first-network-policy.md

Initializes a new sandbox without automatic provider setup.

```shell
openshell sandbox create --name demo --no-auto-providers
```

--------------------------------

### Install Ollama

Source: https://docs.nvidia.com/openshell/get-started/tutorials/inference-ollama.md

Executes the official Ollama installation script on the gateway host.

```shell
curl -fsSL https://ollama.com/install.sh | sh
```

--------------------------------

### Refresh Status Output Examples

Source: https://docs.nvidia.com/openshell/sandboxes/providers-v2.md

Example outputs from the status command showing operational state or missing configurations.

```text
PROVIDER                CREDENTIAL_KEY                STRATEGY                     STATUS              EXPIRES_AT            NEXT_REFRESH          LAST_REFRESH          LAST_ERROR
my-graph                MS_GRAPH_ACCESS_TOKEN         oauth2_refresh_token         refreshed           2026-06-01 00:00:00   2026-05-31 23:50:00   2026-05-31 23:00:00   -
```

```text
No refresh configurations found for provider 'my-graph'.
No refresh configuration found for provider 'my-graph' credential 'MS_GRAPH_ACCESS_TOKEN'.
```

--------------------------------

### Start the Gateway

Source: https://docs.nvidia.com/openshell/get-started/tutorials/docker-compose.md

Commands to navigate to the deployment directory and start the services in detached mode.

```shell
cd deploy/docker
docker compose up -d
```

--------------------------------

### Example rule specification

Source: https://docs.nvidia.com/openshell/sandboxes/policies.md

A concrete example of a rule targeting a GitHub API endpoint.

```text
api.github.com:443:POST:/repos/*/issues
```

--------------------------------

### Install llmster Headless Server

Source: https://docs.nvidia.com/openshell/get-started/tutorials/local-inference-lmstudio.md

Use these commands to install the headless LM Studio server on different operating systems.

```shell
curl -fsSL https://lmstudio.ai/install.sh | bash
```

```powershell
irm https://lmstudio.ai/install.ps1 | iex
```

--------------------------------

### Install OpenShell Helm Chart

Source: https://docs.nvidia.com/openshell/kubernetes/setup.md

Installs the OpenShell chart from the GHCR OCI registry. Use the version-specific command for stable releases or the dev version for the latest build.

```shell
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell
```

```shell
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version 0.0.0-dev \
  --namespace openshell
```

--------------------------------

### Start Ollama Service

Source: https://docs.nvidia.com/openshell/get-started/tutorials/inference-ollama.md

Starts the Ollama server bound to all interfaces to allow sandbox access.

```shell
OLLAMA_HOST=0.0.0.0:11434 ollama serve
```

```shell
systemctl stop ollama
OLLAMA_HOST=0.0.0.0:11434 ollama serve
```

--------------------------------

### Start Gateway with Docker Compose

Source: https://docs.nvidia.com/openshell/about/container-gateway.md

Launches the gateway service using the provided production-ready Compose configuration.

```shell
docker compose -f deploy/docker/docker-compose.yml up -d
```

--------------------------------

### Launch OpenCode in Sandbox

Source: https://docs.nvidia.com/openshell/providers/google-vertex-ai.md

Command to start OpenCode using the local inference gateway, requiring the /v1 path suffix.

```shell
ANTHROPIC_BASE_URL="https://inference.local/v1" ANTHROPIC_API_KEY=unused opencode
```

--------------------------------

### Connect Docker plug

Source: https://docs.nvidia.com/openshell/about/installation.md

Manually connects the Docker plug to the system daemon after installation.

```shell
sudo snap connect openshell:docker docker:docker-daemon
```

--------------------------------

### Run Gateway with Podman

Source: https://docs.nvidia.com/openshell/about/container-gateway.md

Starts the gateway container using Podman with the necessary socket mounts and environment variables.

```shell
podman run -d \
  --name openshell-gateway \
  -p 127.0.0.1:8080:8080 \
  -v openshell-state:/var/openshell \
  -v "$XDG_RUNTIME_DIR/podman/podman.sock:/var/run/podman.sock" \
  -e OPENSHELL_DRIVERS=podman \
  -e OPENSHELL_PODMAN_SOCKET=/var/run/podman.sock \
  -e OPENSHELL_DB_URL=sqlite:/var/openshell/openshell.db \
  -e OPENSHELL_DISABLE_TLS=true \
  ghcr.io/nvidia/openshell/gateway:latest
```

--------------------------------

### Manage the gateway with Docker Compose commands

Source: https://docs.nvidia.com/openshell/get-started/tutorials/docker-compose.md

Common commands for starting, stopping, and monitoring the gateway container.

```bash
docker compose up -d
```

```bash
docker compose down
```

```bash
docker compose logs -f
```

```bash
docker compose pull
```

--------------------------------

### Define Sandbox Policy YAML

Source: https://docs.nvidia.com/openshell/sandboxes/policies.md

Example configuration showing static filesystem and landlock settings alongside dynamic network policies and middlewares.

```yaml
version: 1

# Static: locked at sandbox creation. Paths the agent can read vs read/write.
filesystem_policy:
  include_workdir: true
  read_only: [/usr, /lib, /etc]
  read_write: [/tmp]

# Static: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports.
landlock:
  compatibility: best_effort

# Static, optional: override the identity selected by the compute driver.
# process:
#   run_as_user: "1500"
#   run_as_group: "1500"

# Dynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them.
network_policies:
  my_api:
    name: my-api
    endpoints:
      - host: api.example.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: full
    binaries:
      - path: /usr/bin/curl

# Dynamic: ordered middleware selected independently by admitted host.
network_middlewares:
  regex-redactor:
    name: Redact API tokens
    middleware: openshell/regex
    order: 10
    config:
      mode: redact
    on_error: fail_closed
    endpoints:
      include: ["api.example.com"]
      exclude: []
```

--------------------------------

### Start gateway with mTLS enabled

Source: https://docs.nvidia.com/openshell/about/container-gateway.md

Run the gateway container with the necessary environment variables and volume mounts for TLS certificate paths.

```shell
docker run -d \
  --name openshell-gateway \
  --restart unless-stopped \
  --group-add docker \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/.local/state/openshell:/home/openshell/.local/state/openshell" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/openshell/supervisor/openshell-sandbox:~/openshell/supervisor/openshell-sandbox:ro \
  -e OPENSHELL_DRIVERS=docker \
  -e OPENSHELL_GRPC_ENDPOINT=https://127.0.0.1:8080 \
  -e OPENSHELL_DOCKER_SUPERVISOR_BIN=~/openshell/supervisor/openshell-sandbox \
  -e OPENSHELL_DB_URL=sqlite:/home/openshell/.local/state/openshell/openshell.db \
  -e OPENSHELL_LOCAL_TLS_DIR=/home/openshell/.local/state/openshell/tls \
  -e OPENSHELL_TLS_CERT=/home/openshell/.local/state/openshell/tls/server/tls.crt \
  -e OPENSHELL_TLS_KEY=/home/openshell/.local/state/openshell/tls/server/tls.key \
  -e OPENSHELL_TLS_CLIENT_CA=/home/openshell/.local/state/openshell/tls/ca.crt \
  -e OPENSHELL_ENABLE_MTLS_AUTH=true \
  -e OPENSHELL_DOCKER_TLS_CA=/home/openshell/.local/state/openshell/tls/ca.crt \
  -e OPENSHELL_DOCKER_TLS_CERT=/home/openshell/.local/state/openshell/tls/client/tls.crt \
  -e OPENSHELL_DOCKER_TLS_KEY=/home/openshell/.local/state/openshell/tls/client/tls.key \
  ghcr.io/nvidia/openshell/gateway:latest
```

--------------------------------

### Install OpenShell with Gateway API

Source: https://docs.nvidia.com/openshell/kubernetes/ingress.md

Deploys OpenShell using Helm with GRPCRoute and Envoy Gateway enabled.

```shell
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell \
  --set grpcRoute.enabled=true \
  --set grpcRoute.gateway.create=true \
  --set grpcRoute.gateway.className=eg
```

--------------------------------

### View L7 endpoint summary

Source: https://docs.nvidia.com/openshell/sandboxes/policy-advisor.md

Example output format for L7 proposal endpoint summaries.

```text
Endpoints: api.github.com:443 [L7 rest, allow PUT /repos/NVIDIA/OpenShell/contents/docs/**]
```

--------------------------------

### REST Allow Rules Configuration

Source: https://docs.nvidia.com/openshell/reference/policy-schema.md

Example configuration for REST allow rules using method, path, and query parameter matching.

```yaml
rules:
  - allow:
      method: GET
      path: /**/info/refs*
      query:
        service: "git-*"
  - allow:
      method: POST
      path: /**/git-upload-pack
      query:
        tag:
          any: ["v1.*", "v2.*"]
```

--------------------------------

### Deploy OpenShell with Helm

Source: https://docs.nvidia.com/openshell/kubernetes/setup.md

Use this command to install or upgrade the OpenShell release using a custom values file.

```shell
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell \
  --values my-values.yaml
```

--------------------------------

### Install OpenShell with HTTPS Termination

Source: https://docs.nvidia.com/openshell/kubernetes/ingress.md

Configures OpenShell with an HTTPS listener, TLS certificate reference, and OIDC issuer settings.

```shell
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell \
  --set grpcRoute.enabled=true \
  --set grpcRoute.gateway.create=true \
  --set grpcRoute.gateway.className=eg \
  --set grpcRoute.gateway.listener.protocol=HTTPS \
  --set grpcRoute.gateway.listener.port=443 \
  --set 'grpcRoute.gateway.listener.tls.certificateRefs[0].name=openshell-ingress-tls' \
  --set server.disableTls=true \
  --set server.oidc.issuer=https://<issuer> \
  --set 'grpcRoute.hostnames[0]=<external-hostname>'
```

--------------------------------

### Log Flag Examples

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Examples of flags used with the logs command.

```shell
openshell logs my-sandbox --tail
```

```shell
--source sandbox
```

```shell
--level warn
```

```shell
--since 5m
```

--------------------------------

### Create Google Vertex AI provider from existing environment

Source: https://docs.nvidia.com/openshell/providers/google-vertex-ai.md

Initializes the provider using credentials and configuration already present in the shell environment variables.

```shell
openshell provider create \
  --name vertex-env \
  --type google-vertex-ai \
  --from-existing
```

--------------------------------

### Create Sandbox from Custom Sources

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Initialize a sandbox using base images, local directories, or container registries.

```shell
openshell sandbox create --from base
openshell sandbox create --from ollama
openshell sandbox create --from ./my-sandbox-dir
openshell sandbox create --from my-registry.example.com/my-image:latest
```

--------------------------------

### Run the automated sandbox policy demo

Source: https://docs.nvidia.com/openshell/get-started/tutorials/first-network-policy.md

Executes the full walkthrough script to demonstrate network policy enforcement without manual interaction.

```shell
bash examples/sandbox-policy-quickstart/demo.sh
```

--------------------------------

### Download and load a model in LM Studio

Source: https://docs.nvidia.com/openshell/get-started/tutorials/local-inference-lmstudio.md

Use the lms CLI to fetch and initialize a model for local inference.

```shell
lms get qwen/qwen3.5-2b
lms load qwen/qwen3.5-2b
```

--------------------------------

### Perform GET Request

Source: https://docs.nvidia.com/openshell/get-started/tutorials/first-network-policy.md

Executes a GET request to verify read access, followed by the expected output.

```shell
curl -s https://api.github.com/zen
```

```text
Anything added dilutes everything else.
```

--------------------------------

### Create a Podman bind mount

Source: https://docs.nvidia.com/openshell/reference/sandbox-compute-drivers.md

Attach a host filesystem path to the sandbox after enabling bind mounts in the driver configuration.

```shell
openshell sandbox create \
  --driver-config-json '{"podman":{"mounts":[{"type":"bind","source":"/srv/openshell/work","target":"/sandbox/work","read_only":false}]}}' \
  -- claude
```

--------------------------------

### Create Base Sandbox

Source: https://docs.nvidia.com/openshell/get-started/quickstart.md

Initialize a sandbox using the base container image.

```shell
openshell sandbox create --from base
```

--------------------------------

### Create a Workspace

Source: https://docs.nvidia.com/openshell/sandboxes/manage-workspaces.md

Initialize a new workspace using the OpenShell CLI.

```shell
openshell workspace create --name team-ml
```

--------------------------------

### Create a Provider Instance

Source: https://docs.nvidia.com/openshell/sandboxes/providers-v2.md

Initializes a new provider instance required before configuring refresh settings.

```shell
openshell provider create \
  --name my-graph \
  --type microsoft-graph-mail \
  --credential MS_GRAPH_ACCESS_TOKEN
```

--------------------------------

### Create a provider from existing local credentials

Source: https://docs.nvidia.com/openshell/sandboxes/providers-v2.md

Initializes a provider instance using local credentials discovered through the profile's discovery section.

```shell
openshell provider create \
  --name work-claude \
  --type claude-code \
  --from-existing
```

--------------------------------

### GET /v1/proposals/{chunk_id}

Source: https://docs.nvidia.com/openshell/sandboxes/policy-advisor.md

Retrieves the status of a specific proposal.

```APIDOC
## GET /v1/proposals/{chunk_id}

### Description
Returns one proposal's current pending, approved, or rejected status.

### Method
GET

### Endpoint
/v1/proposals/{chunk_id}

### Parameters
#### Path Parameters
- **chunk_id** (string) - Required - The unique identifier for the proposal chunk.
```

--------------------------------

### Launch a Sandbox with Microsoft Graph Provider

Source: https://docs.nvidia.com/openshell/get-started/tutorials/microsoft-graph-provider-refresh.md

Creates a new sandbox environment with the microsoft-mail provider attached.

```shell
openshell sandbox create \
  --name microsoft-graph-mail \
  --provider microsoft-mail \
  --no-auto-providers \
  -- /bin/sh
```

--------------------------------

### Create Kubernetes Namespace

Source: https://docs.nvidia.com/openshell/kubernetes/setup.md

Creates the dedicated namespace for the OpenShell installation.

```shell
kubectl create namespace openshell
```

--------------------------------

### Verify cert-manager installation

Source: https://docs.nvidia.com/openshell/kubernetes/managing-certificates.md

Checks the status of cert-manager pods in the designated namespace.

```shell
kubectl -n cert-manager get pods
```

--------------------------------

### Create an OpenAI-compatible provider

Source: https://docs.nvidia.com/openshell/get-started/tutorials/local-inference-lmstudio.md

Register LM Studio as an OpenAI-compatible provider using the host.openshell.internal address.

```shell
openshell provider create \
    --name lmstudio \
    --type openai \
    --credential OPENAI_API_KEY=lmstudio \
    --config OPENAI_BASE_URL=http://host.openshell.internal:1234/v1
```

--------------------------------

### GET /v1/denials

Source: https://docs.nvidia.com/openshell/sandboxes/policy-advisor.md

Retrieves recent denied OCSF shorthand log lines.

```APIDOC
## GET /v1/denials

### Description
Returns recent denied OCSF shorthand log lines, newest first. Query strings are redacted before lines are returned to the agent.

### Method
GET

### Endpoint
/v1/denials

### Parameters
#### Query Parameters
- **last** (integer) - Optional - Number of recent logs to return.
```

--------------------------------

### GET /v1/policy/current

Source: https://docs.nvidia.com/openshell/sandboxes/policy-advisor.md

Retrieves the current effective sandbox policy in YAML format.

```APIDOC
## GET /v1/policy/current

### Description
Returns the current effective sandbox policy as YAML.

### Method
GET

### Endpoint
/v1/policy/current
```

--------------------------------

### Create a provider instance for token-grant-only profiles

Source: https://docs.nvidia.com/openshell/sandboxes/providers-v2.md

Use this command to register a provider instance with runtime-resolved credentials.

```shell
openshell provider create \
  --name spiffe-token-demo \
  --type spiffe-token-demo \
  --runtime-credentials
```

--------------------------------

### Configure Vertex AI Provider and Sandbox

Source: https://docs.nvidia.com/openshell/providers/google-vertex-ai.md

Commands to enable the provider, create the configuration, set up inference routing, and initialize a sandbox.

```shell
# 1. Enable provider endpoint injection
openshell settings set --global --key providers_v2_enabled --value true --yes

# 2. Create the provider
openshell provider create \
  --name vertex-local \
  --type google-vertex-ai \
  --from-gcloud-adc \
  --config VERTEX_AI_PROJECT_ID=my-gcp-project \
  --config VERTEX_AI_REGION=us-central1

# 3. Configure inference routing
openshell inference set --provider vertex-local --model claude-sonnet-4-6 --no-verify

# 4. Create a sandbox with the provider attached
openshell sandbox create --name my-sandbox --provider vertex-local
```

--------------------------------

### Apply Agent Sandbox manifest

Source: https://docs.nvidia.com/openshell/kubernetes/setup.md

Installs the Agent Sandbox controller and CRDs into the cluster.

```shell
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml
```

--------------------------------

### List available provider profiles

Source: https://docs.nvidia.com/openshell/sandboxes/manage-providers.md

View known endpoints and binaries before creating a provider.

```shell
openshell provider list-profiles
```

--------------------------------

### Connect to Sandbox

Source: https://docs.nvidia.com/openshell/get-started/tutorials/first-network-policy.md

Establishes a connection to the specified sandbox environment.

```shell
openshell sandbox connect demo
```

--------------------------------

### Create OpenShift Namespace

Source: https://docs.nvidia.com/openshell/kubernetes/openshift.md

Pre-create the namespace to allow for SCC binding before chart installation.

```shell
oc create ns openshell
```

--------------------------------

### Install cert-manager via Helm

Source: https://docs.nvidia.com/openshell/kubernetes/managing-certificates.md

Deploys cert-manager from the OCI registry with CRDs enabled.

```shell
helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.20.3 \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true \
  --wait
```

--------------------------------

### Register gateway with mTLS

Source: https://docs.nvidia.com/openshell/about/container-gateway.md

Use the CLI to register the newly started gateway instance.

```shell
openshell gateway add https://127.0.0.1:8080 --local --name local
```

--------------------------------

### Launch OpenShell Terminal

Source: https://docs.nvidia.com/openshell/get-started/tutorials/github-sandbox.md

Starts the OpenShell terminal session to access sandbox logs.

```shell
openshell term
```

--------------------------------

### GET /v1/proposals/{chunk_id}/wait

Source: https://docs.nvidia.com/openshell/sandboxes/policy-advisor.md

Blocks until a proposal status changes or timeout occurs.

```APIDOC
## GET /v1/proposals/{chunk_id}/wait

### Description
Holds one HTTP request open until the proposal is approved, rejected, or the timeout expires.

### Method
GET

### Endpoint
/v1/proposals/{chunk_id}/wait

### Parameters
#### Path Parameters
- **chunk_id** (string) - Required - The unique identifier for the proposal chunk.

#### Query Parameters
- **timeout** (integer) - Optional - Timeout in seconds.
```

--------------------------------

### Get Sandbox Details

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Commands to retrieve detailed sandbox information or policy configuration.

```shell
openshell sandbox get my-sandbox
```

```shell
openshell sandbox get my-sandbox --output json
```

```shell
openshell sandbox get my-sandbox --policy-only
```

--------------------------------

### Create a Sandbox

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Initialize a new sandbox environment for a specific AI agent.

```shell
openshell sandbox create -- claude
```

```shell
openshell sandbox create --output json
```

--------------------------------

### Configure sandbox environment variables

Source: https://docs.nvidia.com/openshell/providers/aws-sigv4.md

Set these placeholder credentials in the sandbox environment to allow the proxy to perform transparent re-signing.

```shell
export AWS_ACCESS_KEY_ID=placeholder
export AWS_SECRET_ACCESS_KEY=placeholder
export AWS_DEFAULT_REGION=us-east-1
```

--------------------------------

### Install Envoy Gateway via Helm

Source: https://docs.nvidia.com/openshell/kubernetes/ingress.md

Deploys the Envoy Gateway controller and CRDs into the cluster.

```shell
helm install eg \
  oci://docker.io/envoyproxy/gateway-helm \
  --version v1.8.1 \
  --namespace envoy-gateway-system \
  --create-namespace \
  --wait
```

--------------------------------

### Verify OpenShell Status

Source: https://docs.nvidia.com/openshell/about/installation.md

Checks that the CLI is correctly installed and able to communicate with the local gateway.

```shell
openshell status
```

--------------------------------

### Create a provider from existing environment variables

Source: https://docs.nvidia.com/openshell/sandboxes/manage-providers.md

Automatically discover credentials like ANTHROPIC_API_KEY or CLAUDE_API_KEY from the shell environment.

```shell
openshell provider create --name my-claude --type claude --from-existing
```

--------------------------------

### Update Ollama

Source: https://docs.nvidia.com/openshell/get-started/tutorials/inference-ollama.md

Commands to update the Ollama installation manually or automatically upon sandbox creation.

```shell
update-ollama
```

```shell
openshell sandbox create --from ollama -e OLLAMA_UPDATE=1
```

--------------------------------

### Connect to a Sandbox

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Establishes an SSH session or launches an IDE directly into a running sandbox workspace.

```shell
openshell sandbox connect my-sandbox
```

```shell
openshell sandbox create --editor vscode --name my-sandbox
openshell sandbox connect my-sandbox --editor cursor
```

--------------------------------

### openshell sandbox create

Source: https://docs.nvidia.com/openshell/reference/sandbox-compute-drivers.md

Creates a new sandbox with specific Podman driver mount configurations provided via JSON.

```APIDOC
## openshell sandbox create

### Description
Creates a new sandbox instance using the Podman driver. Mount configurations are passed as a JSON string to the `--driver-config-json` flag.

### Parameters
- **--driver-config-json** (string) - Required - A JSON object containing the `podman` configuration, specifically the `mounts` array.

### Request Example
```json
{
  "podman": {
    "mounts": [
      {
        "type": "volume",
        "source": "openshell-work",
        "target": "/sandbox/work",
        "read_only": false
      }
    ]
  }
}
```
```

--------------------------------

### Install OpenShell with cert-manager

Source: https://docs.nvidia.com/openshell/kubernetes/managing-certificates.md

Upgrades the OpenShell Helm release with cert-manager enabled for PKI management.

```shell
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell \
  --set certManager.enabled=true
```

--------------------------------

### Upload Files at Creation

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Upload multiple paths to the sandbox during the creation process using the --upload flag.

```shell
openshell sandbox create --upload ./src:/workspace/src --upload ./config:/workspace/config -- claude
```

--------------------------------

### CLI/TUI Log Output

Source: https://docs.nvidia.com/openshell/observability/logging.md

Example of how logs appear when viewed through the CLI or TUI via gRPC.

```text
[1775014132.118] [sandbox] [OCSF ] [ocsf] NET:OPEN [INFO] ALLOWED /usr/bin/curl(58) -> api.github.com:443 [policy:github_api engine:opa]
[1775014132.690] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(64) -> httpbin.org:443 [policy:- engine:opa] [reason:no matching policy]
[1775014113.058] [sandbox] [INFO ] [openshell_sandbox] Starting sandbox
```

--------------------------------

### System-managed gateway directory structure

Source: https://docs.nvidia.com/openshell/reference/gateway-auth.md

The layout for read-only default gateway configurations provided by installers in /etc/openshell/.

```text
/etc/openshell/
  active_gateway
  gateways/
    <name>/
      metadata.json
```

--------------------------------

### Set CPU and Memory Limits

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Define resource constraints for the sandbox using Kubernetes-style quantities.

```shell
openshell sandbox create --cpu 2 --memory 4Gi -- claude
```

--------------------------------

### Standard Tracing Log Format

Source: https://docs.nvidia.com/openshell/observability/logging.md

Example of internal operational events generated by the Rust tracing framework.

```text
2026-04-01T03:28:39.160Z INFO openshell_sandbox: Fetching sandbox policy via gRPC
2026-04-01T03:28:39.175Z INFO openshell_sandbox: Creating OPA engine from proto policy data
```

--------------------------------

### Middleware Denial Response Structure

Source: https://docs.nvidia.com/openshell/extensibility/supervisor-middleware.md

Example of the JSON response returned when a request is denied by configured middleware.

```json
{
  "error": "middleware_denied",
  "detail": "Request rejected by configured middleware",
  "policy": "api-policy",
  "middleware": "prototype-content-guard",
  "reason_code": "content_match"
}
```

--------------------------------

### Create Sandbox with Driver-specific Configuration

Source: https://docs.nvidia.com/openshell/reference/sandbox-compute-drivers.md

Pass experimental configuration to the active driver using a JSON object keyed by the driver name.

```shell
openshell sandbox create \
  --driver-config-json '{"kubernetes":{"pod":{"runtime_class_name":"kata-containers","priority_class_name":"batch-low"}}}' \
  -- claude
```

--------------------------------

### Manage Port Forwarding

Source: https://docs.nvidia.com/openshell/sandboxes/manage-sandboxes.md

Commands to start, list, and stop port forwards for accessing sandbox services.

```shell
openshell forward start 8000 my-sandbox
openshell forward start 8000 my-sandbox -d    # run in background
```

```shell
openshell forward list
openshell forward stop 8000 my-sandbox
```
Tokens:
Raw