Skip to main content

SDK Install & Setup

The TypeScript SDK (@nanoterm/sdk) is a thin wrapper over the HTTP API. Your agent code uses it the same way as any other client library — create a workspace, exec commands, stream a terminal.

Install​

npm install @nanoterm/sdk
# or
pnpm add @nanoterm/sdk
# or
bun add @nanoterm/sdk

Initialize​

import { NanoTermClient } from '@nanoterm/sdk'

const client = new NanoTermClient({
  apiKey: process.env.NANOTERM_API_KEY!,
})
OptionDefaultWhen to set
apiKey—Always. Issue one from the dashboard.
baseUrlhttps://api.nanoterm.devLocal dev or staging (http://localhost:3000).
clientNamenanoterm-sdkIdentify your app in audit logs and version-gate decisions.
clientVersion(current SDK version)Override only if you re-bundle the SDK and want a custom value.

The SDK sends X-Client-Name and X-Client-Version on every request. The API uses them to populate audit logs and to enforce the minimum-CLI-version gate (426 CLI_VERSION_TOO_OLD). The gate only fires for clientName === "nanoterm-cli", so the default of nanoterm-sdk is what you want for application code.

note

The SDK does not read environment variables implicitly. Pass apiKey explicitly so the source of the key is visible at the call site.

Error handling​

The SDK uses native fetch and throws on network failures. HTTP errors come back as the shared error envelope:

try {
  const ws = await client.createWorkspace({ image: 'ubuntu:22.04' })
} catch (err) {
  // network or non-2xx response
  console.error(err)
}

Transient retries​

The SDK transparently retries on transient classes of failure — 502 / 503 / 504, network errors, and non-JSON CDN error pages — up to 3 times with [500ms, 1500ms, 4000ms] backoff. Structured 4xx and 5xx error envelopes do not retry; they throw immediately so your code can react to them. This means Unexpected end of JSON input from upstream proxy hiccups won't surface to your code in practice.

Next steps​