Get started - Namespace Documentation

Use the Compute API client to create Linux, macOS, or Windows instances from a Node.js application. Create a client and provision your first instance.

Create your first instance

The following example creates a Linux instance with 2 vCPUs and 4 GiB of memory, prints its instance ID, and waits for it to start.

Authenticate with Namespace

For local development, authenticate with the Namespace CLI:

nsc login

The SDK uses a Namespace workload token when available and otherwise the local user token created by nsc login.

Create a Compute client

Import createComputeClient() and create a client:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

The client loads credentials on its first authenticated request and uses the us regional endpoint by default.

Create an instance

Create a Linux instance with a 30-minute deadline:

import { timestampFromDate } from "@bufbuild/protobuf/wkt";

const instance = await client.compute.createInstance({
  shape: {
    os: "linux",
    machineArch: "amd64",
    virtualCpu: 2,
    memoryMegabytes: 4 * 1024,
  },
  documentedPurpose: "TypeScript SDK example",
  deadline: timestampFromDate(new Date(Date.now() + 30 * 60 * 1000)),
});

The deadline releases the instance after 30 minutes.

Print the instance ID

Read the instance ID from the response metadata:

const instanceId = instance.metadata!.instanceId;
console.log(`Created instance: ${instanceId}`);

Wait for the instance

Instance creation is asynchronous. Wait until the instance reaches the RUNNING state:

await client.compute.waitInstanceSync(
  { instanceId },
  { timeoutMs: 10 * 60 * 1000 },
);

console.log("Instance is running");

Show Complete example

import { timestampFromDate } from "@bufbuild/protobuf/wkt";
import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

const instance = await client.compute.createInstance({
  shape: {
    os: "linux",
    machineArch: "amd64",
    virtualCpu: 2,
    memoryMegabytes: 4 * 1024,
  },
  documentedPurpose: "TypeScript SDK example",
  deadline: timestampFromDate(new Date(Date.now() + 30 * 60 * 1000)),
});

const instanceId = instance.metadata!.instanceId;
console.log(`Created instance: ${instanceId}`);

await client.compute.waitInstanceSync(
  { instanceId },
  { timeoutMs: 10 * 60 * 1000 },
);

console.log("Instance is running");

See Create and manage compute instances for request fields, platform examples, placement, readiness handling, and the rest of the instance lifecycle.

Explore Compute

Create and manage instances

Create, wait for, inspect, list, extend, suspend, wake, and destroy instances.

Compute Client

Configure authentication, region, and transport, and see every compute service.

Authenticate with Namespace

Configure credentials for local development and automated workloads.

Access and networking

Expose ingresses and read SSH, VNC, and Kubernetes configuration.

Run commands

Run a command in a container and stream or buffer its output.

Inspect and release volumes

List, describe, and destroy cache and persistent volumes.

Report on usage

Compute, volume, and artifact usage, time series, and reports.

Read logs and egress

Stream and fetch instance logs and egress records.

Compute platform

Learn about platforms, machine shapes, storage, and instance access.

​Create your first instance

​Explore Compute

Create and manage instances

Compute Client

Authenticate with Namespace

Access and networking

Run commands

Inspect and release volumes

Report on usage

Read logs and egress

Compute platform

Create your first instance

Explore Compute