Skip to navigation
SDK Reference

TypeScript SDK

View as Markdown

Use the TypeScript SDK in Node.js applications and automation. It provides a curated sandbox API and a raw generated client for the full gateway RPC surface. Use the SDK and gateway from the same OpenShell release when possible.

Install the SDK

The package requires Node.js 20.3 or later and is currently distributed through GitHub Packages. Configure the @nvidia scope in your project .npmrc:

@nvidia:registry=https://npm.pkg.github.com

Authenticate npm with a GitHub token that has read:packages, then install the package:

npm install @nvidia/openshell-sdk

Connect to a Gateway

OpenShellClient.connect() accepts a gateway URL. It constructs a lazy client, so call health() when startup must verify connectivity:

import { OpenShellClient } from '@nvidia/openshell-sdk'
const client = await OpenShellClient.connect({
  gateway: 'https://gateway.example.com',
  oidcToken: process.env.OPENSHELL_TOKEN,
})
const health = await client.health()
console.log(`${health.status}: ${health.version}`)

For long-running OIDC service automation, use a renewable client-credentials provider:

import { clientCredentials, OpenShellClient } from '@nvidia/openshell-sdk'
const client = await OpenShellClient.connect({
  gateway: 'https://gateway.example.com',
  oidcTokenProvider: clientCredentials({
    issuer: 'https://idp.example.com/realms/openshell',
    clientId: 'openshell-service',
    clientSecret: () => process.env.OPENSHELL_OIDC_CLIENT_SECRET!,
    audience: 'openshell-gateway',
  }),
})

The provider retains credentials and tokens in memory and renews the access token before expiry.

Retrieve Provider Credentials

Connect directly with a trusted OU=operator client certificate after enabling operator authentication. Do not supply an OIDC or edge token for this connection. No sandbox creation or provider attachment is required.

import { readFileSync } from 'node:fs'
import { OpenShellClient } from '@nvidia/openshell-sdk'
const operator = await OpenShellClient.connect({
  gateway: 'https://gateway.example.com',
  caCert: readFileSync('ca.crt'),
  clientCert: readFileSync('operator.crt'),
  clientKey: readFileSync('operator.key'),
})
const credentials = await operator.providers.getCredentials(
  'my-graph',
  ['MS_GRAPH_ACCESS_TOKEN'],
  { workspace: 'production', minimumRemainingLifetimeSecs: 300 },
)
const token = credentials.MS_GRAPH_ACCESS_TOKEN!.value

ProviderClient.connect() provides the same API as a standalone client. Unlike sandbox operations, getCredentials() requires an explicit workspace. It returns a record of ProviderCredentialValue objects with value and optional expirationTime, a Date. Sub-millisecond expiration precision is truncated. minimumRemainingLifetimeSecs accepts fractional seconds; omission or zero uses the gateway default. Pass signal or timeoutMs in the operation options to bound delivery. The helper does not retry or cache exports, and canceled delivery does not roll back a gateway refresh that has already started.

Keep returned values out of logs and shared output. See Retrieve Runtime Credentials for freshness, supported credentials, and the export security boundary.

Create and Use a Sandbox

The curated client uses the default workspace unless you pass workspace in an operation’s options:

const sandbox = await client.sandbox.create({
  name: 'sdk-example',
  image: 'registry.example.com/team/python-agent:1.0',
})
await client.sandbox.waitReady(sandbox.name, 120)
const result = await client.sandbox.exec(
  sandbox.name,
  ['python', '-c', "print('hello from OpenShell')"],
)
console.log(result.stdout.toString())
const deletion = await client.sandbox.delete(sandbox.name)
if (deletion.outcome === 'accepted') {
  await client.sandbox.waitDeleted(sandbox.name, 60, {
    expectedSandboxId: deletion.sandboxId,
  })
}

Sandbox refs returned by create, get, and list include createdAtMs, the creation time in epoch milliseconds. It is absent when the gateway omits it.

client.sandbox also supports streaming and interactive exec, TCP forwarding, SSH sessions, sandbox provider attachment, configuration, and policy. Close operation-scoped streams and forwarding handles when finished. The root client does not retain a dedicated session and has no close() method.

Watch Logs and Events

watchLogs streams a sandbox’s log lines and platform events with automatic reconnect and loss-aware resume. Pass a previous item’s cursor back in as resumeAfterCursor to continue after a restart without gaps or duplicates:

for await (const item of client.sandbox.watchLogs(sandbox.name, { followLogs: true })) {
  if (item.kind === 'log') {
    console.log(`${item.line.level} ${item.line.message}`)
  } else if (item.kind === 'warning') {
    console.warn(`gap: ${item.message}`)
  }
}

See Accessing Logs for the cursor and resume contract this method implements.

Use the Raw Client

Use client.raw for RPCs that the curated clients do not yet wrap. Import generated message schemas and types from @nvidia/openshell-sdk/raw. Raw calls return protobuf wire shapes, while curated calls return SDK-specific types.

Next Steps