Get started

Use the TypeScript SDK to create and operate Namespace Devboxes from Node.js applications. Install the SDK, authenticate with Namespace, create a client, and run a command in your first Devbox.

Install the SDK

Install the SDK and its peer dependencies with your preferred package manager.

npm install @namespacelabs/sdk @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf

pnpm add @namespacelabs/sdk @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf

yarn add @namespacelabs/sdk @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf

This reference imports the Devbox API from @namespacelabs/sdk/devbox. The package root, @namespacelabs/sdk, also re-exports the same API.

Create your first Devbox

Create a Devbox from the Node.js image, run a command, and delete the Devbox when finished. Always close the client to release its cached connections.

import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient();

try {
  const devbox = await client.devboxes.create({
    name: `devbox-created-with-sdk`,
    imageName: "builtin:agents",
  });

  try {
    const result = await devbox.exec(["node", "--version"]);
    if (result.exitCode !== 0) {
      throw new Error(result.error ?? result.stderr);
    }

    console.log(result.stdout.trim());
  } finally {
    await devbox.delete();
  }
} finally {
  client.close();
}

Authenticate with Namespace

For CI/CD and other automated workloads, use workload identity federation to obtain short-lived Namespace credentials without storing a shared token. For local development, install the Devbox CLI and authenticate:

devbox login

The SDK discovers credentials established by federation, the local user token created by devbox login, or a Namespace workload token. See Authenticate with Namespace for the complete resolution order and explicit token sources.

`createDevboxClient()`

Create a client that provides access to Devboxes, blueprints, and images. The client loads credentials when it first makes an authenticated request.

Example

import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient();

API reference

createDevboxClient(options?: DevboxClientOptions): DevboxClient

Arguments and options

DevboxClientOptions

Options used to configure the client.

Hide properties

TokenSourceInput

Provides API tokens for Namespace requests and Devbox connections. Defaults to the Namespace workload token when available, then falls back to the local user token.

Transport

A fully configured Connect transport for Devbox API requests. When provided, baseUrl is ignored and the SDK does not add RPC authentication. The tokenSource is still used to authenticate Devbox connections.

string

The Devbox API URL used by the default transport. Defaults to NSC_DEVBOX_ENDPOINT when set, or the Namespace iad regional endpoint. This does not select where Devboxes are created.

number

default:"90000"

The default timeout, in milliseconds, for establishing a connection to a Devbox.

Return value

createDevboxClient() returns a DevboxClient.

interface DevboxClient {
  devboxes: DevboxResource;
  blueprints: BlueprintResource;
  images: ImageResource;
  close(): void;
}

DevboxResource

required

Creates, finds, lists, and manages Devboxes.

BlueprintResource

required

Creates and manages reusable Devbox configurations.

ImageResource

required

Registers and manages images used by Devboxes and blueprints.

void

required

Closes cached connections held by the client. It does not delete Devboxes or other resources.

Explore the SDK

Create and manage Devboxes

Create Devboxes and control their lifecycle.

Run commands

Execute structured commands and shell scripts.

Use interactive terminals

Open and control pseudo-terminal sessions.

Work with files

Transfer and manipulate files and directories.

Interact with the display

Capture screenshots and send pointer input.

Use blueprints

Create reusable Devbox configurations.

Manage images

Handle errors and timeouts

Cancel operations and handle SDK failures.

Devbox SDK

Automation

CLI

Install the SDK

Create your first Devbox

Authenticate with Namespace

`createDevboxClient()`

Example

API reference

Arguments and options

Return value

Explore the SDK

Create and manage Devboxes

Run commands

Use interactive terminals

Work with files

Interact with the display

Use blueprints

Manage images

Handle errors and timeouts

​Install the SDK

​Create your first Devbox

​Authenticate with Namespace

​createDevboxClient()

​Example

​API reference

​Arguments and options

​Return value

​Explore the SDK

Create and manage Devboxes

Run commands

Use interactive terminals

Work with files

Interact with the display

Use blueprints

Manage images

Handle errors and timeouts

Install the SDK

Create your first Devbox

Authenticate with Namespace

`createDevboxClient()`

Example

API reference

Arguments and options

Return value

Explore the SDK