> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/openshell/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/openshell/_mcp/server.

# Upgrade to NVIDIA OpenShell 0.1.0

> Prepare OpenShell operators and users for the breaking changes in version 0.1.0.

> **Warning**
>
> Local OpenShell 0.0.x installations cannot be upgraded in place. Clean up the
> old runtime and [uninstall the existing package](/about/installation#uninstall-openshell)
> before installing OpenShell 0.1.0.

OpenShell 0.1.0 introduces breaking changes for deployments, sandboxes, policies, APIs, and SDKs. Review the changes that apply to your role before upgrading:

* [Operators](#operators): Plan the rollout, migrate configuration and credentials, and update custom extensions.
* [End users](#end-users): Update sandbox workflows, policies, API clients, and SDK integrations.

## Operators

If you run OpenShell for a team, start here.

* **Coordinate the upgrade.** Stop all gateway replicas, back up the database, and upgrade gateways, compute and credential drivers, supervisors, middleware, CLI clients, and SDK clients from the same release. The protocol, field-name, and time-type changes do not support mixed 0.0.x and 0.1.0 peers ([PR #3113](https://github.com/NVIDIA/OpenShell/pull/3113), [PR #3272](https://github.com/NVIDIA/OpenShell/pull/3272), [PR #3352](https://github.com/NVIDIA/OpenShell/pull/3352)).

* **Recreate every sandbox.** Remove 0.0.x sandboxes before the upgrade and recreate them afterward. The persisted sandbox boundary and runtime descriptors are not compatible with 0.1.0 ([PR #2942](https://github.com/NVIDIA/OpenShell/pull/2942), [PR #3366](https://github.com/NVIDIA/OpenShell/pull/3366)).

* **Export provider profiles before upgrading.** The gateway no longer includes built-in profiles. Import the saved profiles after the upgrade at the same global or workspace scope. Replace profile aliases such as `claude` and `gh` with the canonical IDs `claude-code` and `github` ([PR #2962](https://github.com/NVIDIA/OpenShell/pull/2962), [PR #3383](https://github.com/NVIDIA/OpenShell/pull/3383)).

  ```shell
  openshell provider profile export <id> -o yaml --global > <id>.yaml
  openshell profile import --from ./profiles --global
  ```

* **Migrate `gateway.toml` to schema version 2.** Add the version, replace the plural compute-driver selector, move driver settings under `[openshell.drivers.<name>]`, and apply the renamed Docker, Podman, and VM fields. Validate the file before restarting. See [Gateway Configuration](/how-it-works/gateways/configuration#migrate-to-schema-version-2) for the complete field mapping and [PR #2814](https://github.com/NVIDIA/OpenShell/pull/2814) for the implementation.

  ```toml
  [openshell]
  version = 2

  [openshell.gateway]
  compute_driver = "kubernetes"

  [openshell.drivers.kubernetes]
  namespace = "openshell"
  ```

  ```shell
  openshell-gateway config preflight --path /etc/openshell/gateway.toml
  ```

* **Move Helm application settings to `gatewayConfig`.** Express gateway settings with the schema-v2 TOML hierarchy. Keep TLS keys, passwords, client secrets, RBAC, Services, image settings, and volumes in the chart-owned values and Secret interfaces ([PR #3384](https://github.com/NVIDIA/OpenShell/pull/3384)).

* **Review the default workload image.** The fallback becomes the minimal `nvcr.io/nvidia/base/ubuntu:24.04` image, which includes no agent CLI or image-baked policy. Bare image aliases are removed, so specify a fully qualified image that you built with the required agents, tools, and startup behavior. The runtime fallback policy denies network access and no longer grants `/app`; images without an OCI `USER` run as UID and GID `1000` ([PR #3386](https://github.com/NVIDIA/OpenShell/pull/3386)).

* **Preserve credential encryption material.** New provider credentials use the active gateway credential driver, with encrypted database storage as the default. Preserve the generated key-encryption-key Secret, reconfigure refresh grants, and recreate credentials before switching credential drivers. Do not configure an empty `credential_drivers` list or run mixed gateway versions against the same refresh records ([PR #2437](https://github.com/NVIDIA/OpenShell/pull/2437)).

* **Update Kubernetes user-namespace configuration.** Remove `platform_config.host_users`. Use the typed sandbox template `user_namespaces` field or the Kubernetes driver default ([PR #3248](https://github.com/NVIDIA/OpenShell/pull/3248)).

* **Approve caller-selected compute resources.** Compute drivers now disable caller-supplied `driver_config` by default. If you enable it, label each allowed PVC, RuntimeClass, PriorityClass, Docker volume, or Podman volume with `openshell.ai/sandbox-attachable=true` and `openshell.ai/sandbox-attachable-workspace=<workspace>`. Recreate legacy sandboxes without verifiable admission provenance, pass matching admission settings to standalone drivers, and set `gateway.allowDriverConfig=true` on each split Helm workspace release ([PR #3538](https://github.com/NVIDIA/OpenShell/pull/3538), [PR #3571](https://github.com/NVIDIA/OpenShell/pull/3571)).

* **Review Helm PKI and ingress settings.** PKI initialization now fails an install or upgrade after its timeout by default. Increase `pkiInitJob.timeoutSeconds` when needed, and set `server.tls.enableMtls=false` when enabling `grpcRoute.backendTLSPolicy` ([PR #2728](https://github.com/NVIDIA/OpenShell/pull/2728)).

* **Remove orphaned Helm RBAC objects.** After verifying the new namespace-qualified `ClusterRole` and `ClusterRoleBinding`, delete the old fixed-name `openshell-gateway-node-reader` objects if no release still owns them ([PR #2939](https://github.com/NVIDIA/OpenShell/pull/2939)).

* **Recreate Kubernetes Secrets provider credentials.** The Kubernetes Secrets credential driver stores every provider credential in its configured `namespace` in every workspace mode. Remove the `workspace_mode`, `gateway_id`, and `allow_reference_namespace` driver settings; a `gateway.toml` that sets them is rejected at startup. Credentials stored by the driver are not migrated. Deploy a fresh gateway, then create providers and refresh grants again ([PR #3616](https://github.com/NVIDIA/OpenShell/pull/3616)).

* **Install the workspace chart in operator-managed namespaces.** In operator workspace mode, the gateway receives Secret permissions only from the `openshell-workspace` chart. Install the matching chart release in every operator-managed namespace; without it, sandbox bootstrap fails ([PR #3616](https://github.com/NVIDIA/OpenShell/pull/3616)).

* **Implement extension protocol negotiation.** Custom compute drivers, credential drivers, gateway interceptors, and middleware must exchange `PeerMetadata`, use protocol `1.0`, and advertise their family base capability. Upgrade both peers together. See [Extension Protocol Negotiation](/extensibility/overview#protocol-negotiation) and [PR #3352](https://github.com/NVIDIA/OpenShell/pull/3352).

* **Remove compute-driver callback-listener negotiation.** Regenerate custom compute-driver bindings and connect supervisors to the operator-configured primary gateway endpoint ([PR #3365](https://github.com/NVIDIA/OpenShell/pull/3365)).

* **Update supervisor middleware events.** Accept `MiddlewareDescribeRequest`, replace the WebSocket-specific terminal-event types with the shared middleware types, and handle the renamed and split end reasons ([PR #3073](https://github.com/NVIDIA/OpenShell/pull/3073)).

* **Regenerate extension bindings.** Update canonical request field names and protobuf `Timestamp` and `Duration` fields. Do not reuse generated 0.0.x bindings with 0.1.0 peers ([PR #3113](https://github.com/NVIDIA/OpenShell/pull/3113), [PR #3272](https://github.com/NVIDIA/OpenShell/pull/3272)).

* **Bind authenticated drivers to a runtime identity.** A custom compute driver that advertises `supports_sandbox_authentication` must return a non-empty `runtime_identity` from create, start, and authentication. It must also honor `expected_runtime_identity` during restart so the gateway can bind bootstrap credentials to the current compute resource ([PR #3531](https://github.com/NVIDIA/OpenShell/pull/3531)).

## End users

If you use OpenShell through the CLI, policies, APIs, or SDKs, review these changes.

* **Build local images before sandbox creation.** `openshell sandbox create --from` no longer builds a Dockerfile or directory. Build and tag with the gateway's container engine, then pass the image reference. Remote gateways need an image they can pull from a registry ([PR #3214](https://github.com/NVIDIA/OpenShell/pull/3214)).

  ```shell
  docker build -t registry.example.com/team/agent:0.1.0 .
  docker push registry.example.com/team/agent:0.1.0
  openshell sandbox create --from registry.example.com/team/agent:0.1.0
  ```

* **Name providers explicitly.** A trailing sandbox command no longer infers or attaches a provider. Pass `--provider <name>`, and ask the operator to import the referenced profile when it is missing ([PR #3383](https://github.com/NVIDIA/OpenShell/pull/3383)).

* **Replace managed inference routes.** The `openshell inference` commands, route APIs, and `inference.local` endpoint are removed. Attach a provider to each sandbox and call its native endpoint with its native model and request format. See [Migrate from Managed Inference Routes](/how-it-works/inference#migrate-from-managed-inference-routes) and [PR #3195](https://github.com/NVIDIA/OpenShell/pull/3195).

* **Remove `NetworkBinary.harness`.** In authored policies, keep each binary as an object containing only `path`, such as `- path: /usr/bin/curl`. In provider profiles, write binaries as scalar paths such as `- /usr/bin/curl` ([PR #3222](https://github.com/NVIDIA/OpenShell/pull/3222)).

* **Fix unknown policy fields.** The authored policy schema rejects misspelled, obsolete, and other unknown fields instead of ignoring them ([PR #3334](https://github.com/NVIDIA/OpenShell/pull/3334)).

* **Update endpoint modes.** Regenerate clients for the typed `tls`, `enforcement`, and `access` enums. Remove `tls: terminate` and `tls: passthrough`; omit `tls` for automatic inspection. Do not use `skip` as a replacement because it disables inspection ([PR #3187](https://github.com/NVIDIA/OpenShell/pull/3187), [PR #3414](https://github.com/NVIDIA/OpenShell/pull/3414)).

* **Target L7 policy edits explicitly.** Policy update commands that append allow or deny rules must include `--rule-name` and every `--binary`, or `--any-binary`. Raw API calls must send the complete `L7RuleTarget` ([PR #3380](https://github.com/NVIDIA/OpenShell/pull/3380)).

* **Send the negotiated MCP version.** MCP clients must include one `MCP-Protocol-Version` header on each post-initialization request, and the endpoint policy must allow that revision ([PR #3241](https://github.com/NVIDIA/OpenShell/pull/3241)).

* **Select workspaces explicitly.** Regenerate clients for `WorkspaceSelector`, and select the literal `default` workspace when appropriate. Omission no longer selects it. See [Manage Workspaces](/how-it-works/workspaces) and [PR #3245](https://github.com/NVIDIA/OpenShell/pull/3245).

* **Use canonical resource names.** Public sandbox RPCs accept a sandbox name plus its workspace instead of an internal sandbox ID. Update renamed request and JSON fields such as `sandbox`, `provider`, and `name` ([PR #3272](https://github.com/NVIDIA/OpenShell/pull/3272)).

* **Use protobuf time types.** Replace scalar millisecond, second, and string fields with `google.protobuf.Timestamp` and `google.protobuf.Duration`. Preserve the distinction between an absent field and a zero value. See [Protobuf Time Types](/sdk/protobuf-time-types) and [PR #3113](https://github.com/NVIDIA/OpenShell/pull/3113).

* **Replace offset pagination.** Send `page_size` and the opaque `page_token`, then continue while `next_page_token` is non-empty. Curated SDK list methods may return lazy, single-pass pagers; use `list_all` or `ListAll` only when the full collection is required ([PR #3249](https://github.com/NVIDIA/OpenShell/pull/3249), [PR #3256](https://github.com/NVIDIA/OpenShell/pull/3256), [PR #3279](https://github.com/NVIDIA/OpenShell/pull/3279)).

* **Handle typed deletion outcomes.** Replace `deleted`, `removed`, and `revoked` booleans with `DeletionOutcome`. Treat `ACCEPTED` as asynchronous, use the returned sandbox ID when waiting, and set `allow_missing` only when absence is acceptable. See [SDK Migration for Deletion](/sdk/api-errors#sdk-migration-for-deletion) and [PR #3317](https://github.com/NVIDIA/OpenShell/pull/3317).

* **Update SDK error handling.** Python clients raise `GatewayError`, which is a `grpc.RpcError` but not a `grpc.Call`. Rust error variants contain additional status fields. SDKs expose retry details but do not automatically retry mutations ([PR #3313](https://github.com/NVIDIA/OpenShell/pull/3313)).

* **Use stable request IDs for retries.** When a mutation includes `request_id`, retry with the same identity, scope, method, and payload. Cancellation does not cancel admitted work. Reconcile the result after `REQUEST_OUTCOME_UNCERTAIN` instead of submitting a new ID. An admitted exec retry cannot replay output, its exit code, or the stream, so handle `REQUEST_STREAM_UNAVAILABLE` separately ([PR #3321](https://github.com/NVIDIA/OpenShell/pull/3321), [PR #3323](https://github.com/NVIDIA/OpenShell/pull/3323), [PR #3324](https://github.com/NVIDIA/OpenShell/pull/3324)).

* **Drain interactive exec after closing input.** Closing the request stream closes stdin but does not end output. Drain output concurrently and wait for both the exit event and final RPC status. Go clients use `CloseInteractiveInput` or `CancelInteractive`; TypeScript clients use `closeInput()` or `cancel()` ([PR #3359](https://github.com/NVIDIA/OpenShell/pull/3359)).

* **Resume watch streams by cursor.** Treat stream warnings as recoverable gaps, persist the greatest processed opaque cursor, and send it when reconnecting. If the gateway returns `OUT_OF_RANGE`, discard the cursor and restart without resume ([PR #3209](https://github.com/NVIDIA/OpenShell/pull/3209)).

* **Stop importing persistence messages.** The `StoredProviderProfile`, refresh-state, stored policy revision, and draft-chunk messages move to a private storage package and have no public API replacement ([PR #3169](https://github.com/NVIDIA/OpenShell/pull/3169)).

* **Replace scripted `gateway info` calls.** The command now returns live, admin-gated runtime state. Use `openshell gateway list -o json` for local registration metadata ([PR #2202](https://github.com/NVIDIA/OpenShell/pull/2202)).

* **Stop parsing the profile list table.** The human-readable columns change. Use JSON or YAML output in scripts; the structured profile schema is unchanged ([PR #3258](https://github.com/NVIDIA/OpenShell/pull/3258)).