Sandboxes TypeScript client

The @coreweave/cwsandbox TypeScript client creates and manages CoreWeave sandboxes. Follow this guide to create a client, run a sandbox command, and handle SDK errors. This guide and the API reference cover version 1.0.0.

Prerequisites

Use Node.js 22 or later and an ECMAScript module (ESM) project. Save the examples as .mts files to run them with tsx. Choose a credential from Choose and get credentials. The examples use serverless capacity. For CoreWeave Kubernetes Service (CKS) placement, enable a runner and use a CoreWeave API access token with a non-empty runnerIds array. Install the SDK:

npm install @coreweave/cwsandbox@1.0.0

Create a client

Choose the entry point for your credential. Both factories return a SandboxClient. The root @coreweave/cwsandbox entry point exports types, constants, and errors. Create clients through /wandb or /node. Save the code from your tab as a sandbox-client.mts file beside the other example files. It selects authentication and exports the client. The credential stays in your environment.

Forge API key
CoreWeave API access token

Replace [WANDB-API-KEY] with your Forge API key:

export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

export const client = createSandboxClientFromEnv();

To select a Forge team, set WANDB_ENTITY. For explicit options, see Forge client factories.

Replace [API-ACCESS-TOKEN] with your token:

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

export const client = createSandboxClientFromEnv();

The factory also reads CWSANDBOX_BASE_URL, which defaults to https://api.cwsandbox.com. For explicit options, see Node client factories.

Run a command

For work that should stop when its callback finishes, use withSandbox(). It waits for sandbox readiness before calling the callback and stops the sandbox after the callback returns or throws.

hello.mts

import { client } from "./sandbox-client.mjs";

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
  {
    containerImage: "python:3.11",
    resources: { cpu: "1", memory: "1Gi" },
  },
);

console.log(result.stdout);

Run the script:

npx --yes --package=tsx tsx hello.mts

The script prints Hello! and stops the sandbox. The ./sandbox-client.mjs import resolves to the local sandbox-client.mts file when you run with tsx or compile with TypeScript. commands.run() buffers standard output (stdout) and standard error (stderr) and returns a ProcessResult with exitCode. For streaming output, use commands.start(). To keep the sandbox across operations, use client.create(), then stop it in a finally block. See the sandbox lifecycle reference.

Handle errors

Use isCWSandboxError() to narrow an unknown error and inspect its code:

import { isCWSandboxError } from "@coreweave/cwsandbox";
import { client } from "./sandbox-client.mjs";

try {
  await client.withSandbox(async (sandbox) => {
    await sandbox.commands.run(["false"], { check: true });
  });
} catch (error) {
  if (isCWSandboxError(error)) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}

With check: true, a nonzero command exit raises CWSandboxExecutionError. For the error hierarchy and available metadata, see Errors.

API reference

The reference preserves the published declarations, including method overloads, parameter and return types, optional fields, and inherited types. SDK comments include reviewed corrections.

Reference	Contents
Client and discovery	Create, reconnect, list, clean up, and start from templates or Compose files.
Sandboxes and lifecycle	Sandbox handles, start options, snapshots, and lifecycle states.
Commands and terminals	Command execution, process handles, standard input (stdin), and interactive terminals.
Files	Buffered and streaming file operations and mounted files.
Logs	Read and stream sandbox logs.
Networks and services	Network rules, services, and endpoints.
Resources and secrets	Resource requests and limits and secret inputs.
Request options and defaults	Timeouts, cancellation, data plane modes, and default constants.
Errors	Error classes, codes, and backend reason constants.
Node client factories	CoreWeave token authentication and client construction.
Forge client factories	Forge authentication and team selection.

For a Compose example, see Create a sandbox from TypeScript.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Sandboxes TypeScript client

Prerequisites

Create a client

Run a command

Handle errors

API reference

​Prerequisites

​Create a client

​Run a command

​Handle errors

​API reference

Prerequisites

Create a client

Run a command

Handle errors

API reference