Upgrade Guides

Upgrade to NVIDIA OpenShell 0.1.0

View as Markdown

Upgrading from OpenShell 0.0.x to 0.1.0? Start with the section that matches how you use the platform.

Each item links to the pull request that defines the change.

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, PR #3272, PR #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, PR #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, PR #3383).

    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 for the complete field mapping and PR #2814 for the implementation.

    [openshell]
    version = 2
    [openshell.gateway]
    compute_driver = "kubernetes"
    [openshell.drivers.kubernetes]
    namespace = "openshell"
    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).

  • 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).

  • 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).

  • 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).

  • 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, PR #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).

  • 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).

  • 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).

  • 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).

  • 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 and PR #3352.

  • Remove compute-driver callback-listener negotiation. Regenerate custom compute-driver bindings and connect supervisors to the operator-configured primary gateway endpoint (PR #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).

  • 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, PR #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).

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).

    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).

  • 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 and PR #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).

  • Fix unknown policy fields. The authored policy schema rejects misspelled, obsolete, and other unknown fields instead of ignoring them (PR #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, PR #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).

  • 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).

  • Select workspaces explicitly. Regenerate clients for WorkspaceSelector, and select the literal default workspace when appropriate. Omission no longer selects it. See Manage Workspaces and PR #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).

  • 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 and PR #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, PR #3256, PR #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 and PR #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).

  • 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, PR #3323, PR #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).

  • 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).

  • 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).

  • 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).

  • 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).