> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started

> Install the TypeScript SDK, create a client, and get started with Namespace Devboxes.

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.

<CodeGroup>
  ```bash npm theme={null}
  npm install @namespacelabs/sdk @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf
  ```

  ```bash pnpm theme={null}
  pnpm add @namespacelabs/sdk @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf
  ```

  ```bash Yarn theme={null}
  yarn add @namespacelabs/sdk @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf
  ```
</CodeGroup>

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.

```typescript {6-9,12,19,22} theme={null}
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](/docs/reference/typescript-sdk/authentication#workload-identity-federation) to obtain short-lived Namespace credentials without storing a shared token.

For local development, [install the Devbox CLI](/docs/devbox#install-the-devbox-cli) and authenticate:

```bash theme={null}
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](/docs/reference/typescript-sdk/authentication) 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

```typescript {3} theme={null}
import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient();
```

### API reference

```typescript theme={null}
createDevboxClient(options?: DevboxClientOptions): DevboxClient
```

#### Arguments and options

<ResponseField name="options" type="DevboxClientOptions">
  Options used to configure the client.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="tokenSource" type="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.
    </ResponseField>

    <ResponseField name="transport" type="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.
    </ResponseField>

    <ResponseField name="baseUrl" type="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.
    </ResponseField>

    <ResponseField name="connectionTimeoutMs" type="number" default="90000">
      The default timeout, in milliseconds, for establishing a connection to a Devbox.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Return value

`createDevboxClient()` returns a `DevboxClient`.

```typescript theme={null}
interface DevboxClient {
  devboxes: DevboxResource;
  blueprints: BlueprintResource;
  images: ImageResource;
  close(): void;
}
```

<ResponseField name="devboxes" type="DevboxResource" required>
  Creates, finds, lists, and manages Devboxes.
</ResponseField>

<ResponseField name="blueprints" type="BlueprintResource" required>
  Creates and manages reusable Devbox configurations.
</ResponseField>

<ResponseField name="images" type="ImageResource" required>
  Registers and manages images used by Devboxes and blueprints.
</ResponseField>

<ResponseField name="close()" type="void" required>
  Closes cached connections held by the client. It does not delete Devboxes or other resources.
</ResponseField>

## Explore the SDK

<Columns cols={2}>
  <Card title="Create and manage Devboxes" icon="container" href="/docs/reference/typescript-sdk/devboxes">
    Create Devboxes and control their lifecycle.
  </Card>

  <Card title="Run commands" icon="terminal" href="/docs/reference/typescript-sdk/commands">
    Execute structured commands and shell scripts.
  </Card>

  <Card title="Use interactive terminals" icon="square-terminal" href="/docs/reference/typescript-sdk/terminals">
    Open and control pseudo-terminal sessions.
  </Card>

  <Card title="Work with files" icon="file" href="/docs/reference/typescript-sdk/files">
    Transfer and manipulate files and directories.
  </Card>

  <Card title="Interact with the display" icon="monitor" href="/docs/reference/typescript-sdk/display">
    Capture screenshots and send pointer input.
  </Card>

  <Card title="Use blueprints" icon="layers" href="/docs/reference/typescript-sdk/blueprints">
    Create reusable Devbox configurations.
  </Card>

  <Card title="Manage images" icon="hard-drive" href="/docs/reference/typescript-sdk/images">
    Register, inspect, and optimize images.
  </Card>

  <Card title="Handle errors and timeouts" icon="triangle-alert" href="/docs/reference/typescript-sdk/errors">
    Cancel operations and handle SDK failures.
  </Card>
</Columns>