Get Started with the Devbox SDK

Use the SDK when a program needs to create Devboxes and run work in them: test runners that fan out across machines, agent harnesses that need an isolated sandbox per task, or internal tooling that provisions environments for your team. This page takes you from an empty project to a script that creates a Devbox and runs a command in it.

Getting Started

Authenticate with Namespace

The SDK has no login of its own. It reads the credential written by the Devbox CLI, so install the Devbox CLI and log in once:

devbox login

For automated workloads, use workload identity federation instead. Applications running inside a Namespace workload already receive a credential and need no setup.

Install the SDK

Add the SDK to your project:

npm install @namespacelabs/sdk

pnpm add @namespacelabs/sdk

yarn add @namespacelabs/sdk

The Devbox API lives at @namespacelabs/sdk/devbox. The package root re-exports the same API.

Create a client

The client holds the connection to Namespace. createDevboxClient() resolves the credential from step 1 automatically when tokenSource is omitted.

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

const client = createDevboxClient();

See Create a client for configuration options.

Create a Devbox

devboxes.create() provisions a Devbox and returns a handle you operate on. Devboxes start by default, and the call waits for the Devbox to become ready.

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  // repository: "github.com/your-org/your-repo",
});

console.log(`Created Devbox: ${devbox.name}`);

Setting repository checks out that repository in the Devbox, which requires a connected GitHub organization.

Use devboxes.get() to get a handle for a Devbox that already exists:

const devbox = await client.devboxes.get("my-devbox");

Run a command

devbox.exec() runs a command in the Devbox and resolves once it finishes, giving you its output and exit code.

const result = await devbox.exec(["node", "--version"]);

process.stdout.write(result.stdout);
process.exitCode = result.exitCode;

A non-zero exit code resolves normally rather than throwing, so check exitCode yourself.

Close the client

Close the client when you are finished with it to release its cached connections.

client.close();

Closing the client does not delete the Devbox. Call devbox.delete() to remove it, or create it with ephemeral: true so its instance and storage are discarded when it stops.

The complete script

The steps above assemble into one file:

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

const client = createDevboxClient();

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
});

const result = await devbox.exec(["node", "--version"]);
process.stdout.write(result.stdout);

client.close();

Other ways to run commands

exec() covers most cases. Use one of these when it does not.

shell
terminal
terminal (attached)

devbox.shell() runs a script through the Devbox’s configured shell. Use it for pipes, redirects, variable expansion, or chained commands.

const result = await devbox.shell("node --version | tee version.txt");

process.stdout.write(result.stdout);
process.exitCode = result.exitCode;

devbox.terminal.open() opens an interactive session. Use it for continuous input, REPLs, or programs that require a TTY.

const terminal = await devbox.terminal.open({ columns: 120, rows: 40 });
terminal.onData((data) => process.stdout.write(data));
terminal.write("node --version\n");

terminal.close();

Attach your process’s stdin and stdout to the session so the user types directly into the Devbox shell. The session runs until the remote shell ends, such as when the user types exit.

const terminal = await devbox.terminal.open({ columns: 120, rows: 40 });

const forwardInput = (data: Buffer) => terminal.write(data);

try {
  terminal.onData((data) => process.stdout.write(data));

  process.stdin.setRawMode(true);
  process.stdin.resume();
  process.stdin.on("data", forwardInput);

  const result = await terminal.wait();

  process.exitCode = result.exitCode ?? 1;
} finally {
  process.stdin.off("data", forwardInput);
  process.stdin.pause();
  terminal.close();
}

See Run commands for when to choose exec() over shell(), and Use interactive terminals for the full terminal interface.

TypeScript SDK reference

The reference documents the complete SDK surface, starting with installation and a first Devbox.

Devboxes

Creation options and lifecycle operations.

Commands

exec(), shell(), their options, and their results.

Authentication

Workload identity federation, local credentials, and token sources.

Set this up with a coding agent

Hand your agent the prompt below instead of following the steps above. It installs the Namespace devboxes agent skill, which covers the CLI setup, then points the agent at the SDK reference so it writes against the current API. You will need to complete the login in your browser when the agent reaches that step.

Agent Prompt

Install the Namespace devboxes agent skill, then use it to get me set up:

  npx skills add namespacelabs/agent-skills

Following that skill:

1. Install the Devbox CLI for my operating system, then confirm it works.
2. Log me in to Devbox, then verify that the login succeeded.
3. Read https://namespace.so/docs/reference/typescript-sdk.md and install
   @namespacelabs/sdk with this project's package manager.
4. Read https://namespace.so/docs/reference/typescript-sdk/devboxes.md and
   https://namespace.so/docs/reference/typescript-sdk/commands.md, then write a
   script that creates a Devbox named "first-devbox" from the "builtin:agents"
   image, runs `node --version` in it, prints the output, and closes the client.
5. Run the script and show me the output.

If a documentation link returns a 404, find the current page in
https://namespace.so/docs/llms.txt, an index of every documentation page.

Do not delete or stop any Devbox that already exists in my workspace.

To install the skill yourself, or to install it globally rather than per project, see Agent Skills.

Next steps

Devbox CLI

Create and connect to Devboxes from your terminal.

Agent Skills

Let a coding agent create and drive Devboxes for you.

Blueprints

Reusable Devbox configurations.

Products

Platform

Administration

Getting Started

Authenticate with Namespace

Install the SDK

Create a client

Create a Devbox

Run a command

Close the client

The complete script

Other ways to run commands

TypeScript SDK reference

Devboxes

Commands

Authentication

Set this up with a coding agent

Next steps

Devbox CLI

Agent Skills

Blueprints

​Getting Started

Authenticate with Namespace

Install the SDK

Create a client

Create a Devbox

Run a command

Close the client

​The complete script

​Other ways to run commands

​TypeScript SDK reference

Devboxes

Commands

Authentication

​Set this up with a coding agent

​Next steps

Devbox CLI

Agent Skills

Blueprints

Getting Started

The complete script

Other ways to run commands

TypeScript SDK reference

Set this up with a coding agent

Next steps