Create and manage compute instances - Namespace Documentation

Provision Linux, Linux on Apple Silicon, macOS, or Windows instances, then inspect and control them through client.compute. Instance creation is asynchronous: createInstance() allocates an instance and returns its metadata before the instance necessarily reaches the RUNNING state. The examples on this page use a Compute client:

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

const client = createComputeClient();

See Compute Client to select a region, provide a token source, or supply your own transport.

`compute.createInstance()`

Create an instance and return its metadata and dashboard URL. Instances are micro-VM backed environments optimized to run containers, deployed with containerd and optionally dockerd and Kubernetes.

Example

Create an instance with a 30-minute deadline:

Linux
macOS
Windows
Linux on Apple Silicon

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

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

See Linux machine shapes for supported CPU and memory configurations.

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

const instance = await client.compute.createInstance({
  shape: {
    os: "macos",
    machineArch: "arm64",
    virtualCpu: 6,
    memoryMegabytes: 14 * 1024,
    selectors: [{ name: "macos.version", value: "26.x" }],
  },
  documentedPurpose: "macOS build",
  deadline: timestampFromDate(new Date(Date.now() + 30 * 60 * 1000)),
});

See macOS machine shapes for supported CPU and memory configurations, and macOS base image selection for available selectors.

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

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

See Windows machine shapes for supported CPU and memory configurations.

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

const instance = await client.compute.createInstance({
  shape: {
    os: "linux",
    machineArch: "arm64",
    virtualCpu: 6,
    memoryMegabytes: 14 * 1024,
  },
  documentedPurpose: "Linux ARM64 build",
  deadline: timestampFromDate(new Date(Date.now() + 30 * 60 * 1000)),
});

See Linux on Apple Silicon machine shapes for supported CPU and memory configurations.

API reference

createInstance(
  request: MessageInitShape<typeof CreateInstanceRequestSchema>,
  options?: CallOptions,
): Promise<DescribeInstanceResponse>

Arguments and options

createInstance() accepts a CreateInstanceRequest. Common fields include:

InstanceShape

required

CPU, memory, architecture, operating system, and optional platform selectors for the instance.

Hide properties

number

required

Number of virtual CPUs.

number

required

Memory allocated to the instance, in megabytes.

string

Machine architecture, such as amd64 or arm64.

string

Operating system, such as linux, macos, or windows.

Label[]

Additional platform constraints, such as a macOS version.

string

A human-readable description used to identify and debug the workload.

Timestamp

When Namespace should release the instance. Workspace policy can shorten the requested deadline.

string[]

Ordered placement selectors such as site:iad2, continent:us, or any. When omitted, Namespace selects capacity for the workload.

Label[]

Labels attached to the instance. You can use labels to filter instances when listing them.

ContainerRequest[]

Containers to start during instance creation. Containers are supported on Linux instances.

ApplicationRequest[]

Applications to start directly on the instance without containerization.

VolumeRequest[]

Persistent or cache volumes to attach to the instance.

The request also supports registry credentials, workload permissions, network policy, callbacks, and feature configuration. See the complete CreateInstanceRequest API reference.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

createInstance() returns a DescribeInstanceResponse. Use metadata.instanceId for subsequent Compute API calls and instanceUrl to open the instance in the Namespace dashboard. Extended metadata is returned at creation time and by describeInstance(), but not by listInstances(). See the complete DescribeInstanceResponse API reference. If the workspace is out of resources, the call fails with ResourceExhausted. An invalid argument, such as a non-existing region, fails with InvalidArgument.

More examples

Start a container during creation

Linux instances can start containers as part of the creation request:

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

const instance = await client.compute.createInstance({
  shape: {
    os: "linux",
    machineArch: "amd64",
    virtualCpu: 2,
    memoryMegabytes: 4 * 1024,
  },
  documentedPurpose: "Run nginx",
  deadline: timestampFromDate(new Date(Date.now() + 30 * 60 * 1000)),
  containers: [
    {
      name: "nginx",
      imageRef: "nginx",
    },
  ],
});

Select instance placement

Use ordered placement selectors to constrain where Namespace creates the instance. Namespace tries each selector in order:

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

const instance = await client.compute.createInstance({
  shape: {
    os: "linux",
    machineArch: "amd64",
    virtualCpu: 2,
    memoryMegabytes: 4 * 1024,
  },
  documentedPurpose: "US compute job",
  placement: ["continent:us", "any"],
  deadline: timestampFromDate(new Date(Date.now() + 30 * 60 * 1000)),
});

`compute.waitInstance()`

Wait until an instance reaches the RUNNING state. waitInstanceSync() resolves once the instance is running. waitInstance() is the server-streaming variant: it emits a response for each state progression and the server closes the stream when the instance is running.

Example

Wait for the instance with a 10-minute timeout:

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

instanceId is the value read from metadata.instanceId on the createInstance() response. Use the streaming method when you need intermediate state updates:

for await (const update of client.compute.waitInstance({ instanceId })) {
  console.log(update.metadata?.status);
}

API reference

waitInstanceSync(
  request: MessageInitShape<typeof WaitInstanceRequestSchema>,
  options?: CallOptions,
): Promise<WaitInstanceResponse>

waitInstance(
  request: MessageInitShape<typeof WaitInstanceRequestSchema>,
  options?: CallOptions,
): AsyncIterable<WaitInstanceResponse>

Arguments and options

string

required

The instance to wait for.

boolean

When true, the call does not fail if the instance is destroyed while waiting.

string

Wait for a specific container, identified by the Namespace-allocated container ID.

string

Wait for a specific container by the name given in ContainerRequest.name. When both containerId and containerName are set, containerName takes precedence.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Each WaitInstanceResponse carries metadata, the current InstanceMetadata, and containerStatus. If the instance is already running when the call is made, a single response is returned and the stream closes immediately. If the instance does not exist, the call fails with NotFound. If instance creation is unsuccessful, the call fails with Internal; read metadata.status from the last response for the detailed status.

`compute.startContainers()`

Add containers to a running instance. This is the runtime counterpart to the containers field on createInstance().

Example

const { containers } = await client.compute.startContainers({
  instanceId,
  containers: [
    {
      name: "nginx",
      imageRef: "nginx",
    },
  ],
});

console.log(containers[0]?.id);

API reference

startContainers(
  request: MessageInitShape<typeof StartContainersRequestSchema>,
  options?: CallOptions,
): Promise<StartContainersResponse>

Arguments and options

string

required

The running instance to add containers to.

ContainerRequest[]

required

The additional containers to start. ContainerRequest takes the same shape as at creation time, including name, imageRef or knownImageId, entrypoint, args, envVars, exportPorts, volumes, and privileged. See the complete ContainerRequest API reference.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a StartContainersResponse with containers, the allocated containers in the same order as the request. Each AllocatedContainer carries the Namespace-allocated id, the name you gave it, and any exportedPort entries with their public ingress URLs. If the instance does not exist, the call fails with NotFound.

Namespace-managed containers are treated as critical: if one fails, through an early exit or an out-of-memory kill, the instance fails with it. Containers started through the containerd or Docker APIs yourself are not managed this way.

`compute.describeInstance()`

Fetch the metadata of a previously created instance, including the extended metadata that listInstances() does not return.

Example

const described = await client.compute.describeInstance({ instanceId });

console.log(described.metadata?.status);
console.log(described.instanceUrl);

API reference

describeInstance(
  request: MessageInitShape<typeof DescribeInstanceRequestSchema>,
  options?: CallOptions,
): Promise<DescribeInstanceResponse>

Arguments and options

string

required

The instance to describe.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a DescribeInstanceResponse with instanceUrl, metadata, extendedMetadata, the image registry, allocated containers, attachments, shutdownReasons, and workloadPermissions. If the instance does not exist, the call fails with NotFound.

`compute.listInstances()`

Return one page of instances in the workspace. By default the response only includes instances in the PENDING, CREATING, and RUNNING states.

Example

const page = await client.compute.listInstances({
  maxEntries: 20n,
  includeCompleteRuns: false,
});

for (const metadata of page.instances) {
  console.log(metadata.instanceId, metadata.status);
}

Pass the returned cursor to read the next page:

const first = await client.compute.listInstances({ maxEntries: 20n });

const next = await client.compute.listInstances({
  paginationCursor: first.paginationCursor,
  maxEntries: 20n,
});

API reference

listInstances(
  request: MessageInitShape<typeof ListInstancesRequestSchema>,
  options?: CallOptions,
): Promise<ListInstancesResponse>

Arguments and options

bigint

The maximum number of entries to return. The service returns no more than maxEntries, and may return fewer.

Uint8Array

The paginationCursor from a previous response. Continues reading results with the arguments of the original call.

boolean

When true, also includes instances in the DESTROYED and ERROR states.

Timestamp

Excludes instances created before this timestamp, in UTC.

LabelFilterEntry[]

Only returns instances that match the specified labels.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListInstancesResponse with instances, a list of InstanceMetadata, and a paginationCursor for the next page. Call describeInstance() when you need extended metadata for one of the listed instances.

`compute.extendInstance()`

Extend the lifetime of an instance. Use extendBy to add to the current deadline, ensureMinimum to guarantee a remaining runtime, or newDeadline to set an absolute deadline.

Example

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

const extended = await client.compute.extendInstance({
  instanceId,
  extendBy: durationFromMs(15 * 60 * 1000),
});

console.log(extended.newDeadline);

API reference

extendInstance(
  request: MessageInitShape<typeof ExtendInstanceRequestSchema>,
  options?: CallOptions,
): Promise<ExtendInstanceResponse>

Arguments and options

string

required

The instance to extend.

Duration

The duration to extend the instance by.

Duration

The minimum duration the instance should keep running.

Timestamp

The new deadline, in UTC, at which the instance is destroyed.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an ExtendInstanceResponse with the resulting newDeadline. Workspace policy can shorten the requested deadline. If the instance does not exist, the call fails with NotFound.

`compute.suspendInstance()`

Suspend a running instance. Execution stops and RAM and disks are snapshotted so the instance can be restored without restarting it.

Example

await client.compute.suspendInstance({ instanceId });

API reference

suspendInstance(
  request: MessageInitShape<typeof SuspendInstanceRequestSchema>,
  options?: CallOptions,
): Promise<Empty>

Arguments and options

string

required

The instance to suspend.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an empty response. If the instance does not exist, the call fails with NotFound.

`compute.wakeInstance()`

Wake a suspended instance. The call is a no-op when the instance is already running.

Example

await client.compute.wakeInstance({ instanceId });

API reference

wakeInstance(
  request: MessageInitShape<typeof WakeInstanceRequestSchema>,
  options?: CallOptions,
): Promise<Empty>

Arguments and options

string

required

The instance to wake.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an empty response. If the instance does not exist, the call fails with NotFound. If the instance is neither suspended nor running, the call fails with FailedPrecondition.

`compute.destroyInstance()`

Destroy an instance and release its resources.

Example

await client.compute.destroyInstance({
  instanceId,
  reason: "Work completed",
});

API reference

destroyInstance(
  request: MessageInitShape<typeof DestroyInstanceRequestSchema>,
  options?: CallOptions,
): Promise<Empty>

Arguments and options

string

required

The instance to destroy.

string

A human-readable reason recorded with the request.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an empty response. If the instance does not exist, the call fails with NotFound.

Compute instances are billable resources. Set a deadline and call destroyInstance() when you no longer need an instance.

`compute.releaseUniqueTag()`

Release the instance ID currently associated with a unique tag.

Example

const { instanceId: released } = await client.compute.releaseUniqueTag({
  uniqueTag: "build-runner",
});

console.log(released || "no instance was associated");

API reference

releaseUniqueTag(
  request: MessageInitShape<typeof ReleaseUniqueTagRequestSchema>,
  options?: CallOptions,
): Promise<ReleaseUniqueTagResponse>

Arguments and options

string

required

The unique tag to release.

StringMatcher

Only release the tag when the currently associated instance ID matches.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ReleaseUniqueTagResponse whose instanceId is the instance that was released from the tag, or an empty string when no instance was associated. If the unique tag does not exist, the call fails with NotFound.

Unique tags are assigned through an experimental instance-creation capability. Reach out to the Namespace team before relying on them.Tags are unique per region, so this call must reach the Compute endpoint for the region that holds the tag. Inside an instance, NSC_ENDPOINT points at the endpoint for the current region.

Shared call options

All methods on this page accept Connect CallOptions as their second argument.

CallOptions

Controls cancellation, timeout, and request headers.

Hide properties

number

The call timeout in milliseconds. Set to a value of 0 or less to disable the default timeout.

AbortSignal

Cancels the call when the signal is aborted. A cancelled call raises an error with code Canceled.

HeadersInit

Custom headers to send with the request.

(headers: Headers) => void

Called when response headers are received.

Compute Client

Configure authentication, region, and transport.

Machine shapes

Supported CPU, memory, and platform configurations.

Compute platform

Platforms, storage, networking, and instance access.

​compute.createInstance()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Start a container during creation

​Select instance placement

​compute.waitInstance()

​Example

​API reference

​Arguments and options

​Return value

​compute.startContainers()

​Example

​API reference

​Arguments and options

​Return value

​compute.describeInstance()

​Example

​API reference

​Arguments and options

​Return value

​compute.listInstances()

​Example

​API reference

​Arguments and options

​Return value

​compute.extendInstance()

​Example

​API reference

​Arguments and options

​Return value

​compute.suspendInstance()

​Example

​API reference

​Arguments and options

​Return value

​compute.wakeInstance()

​Example

​API reference

​Arguments and options

​Return value

​compute.destroyInstance()

​Example

​API reference

​Arguments and options

​Return value

​compute.releaseUniqueTag()

​Example

​API reference

​Arguments and options

​Return value

​Shared call options

​Related documentation

Compute Client

Machine shapes

Compute platform

`compute.createInstance()`

Example

API reference

Arguments and options

Return value

More examples

Start a container during creation

Select instance placement

`compute.waitInstance()`

Example

API reference

Arguments and options

Return value

`compute.startContainers()`

Example

API reference

Arguments and options

Return value

`compute.describeInstance()`

Example

API reference

Arguments and options

Return value

`compute.listInstances()`

Example

API reference

Arguments and options

Return value

`compute.extendInstance()`

Example

API reference

Arguments and options

Return value

`compute.suspendInstance()`

Example

API reference

Arguments and options

Return value

`compute.wakeInstance()`

Example

API reference

Arguments and options

Return value

`compute.destroyInstance()`

Example

API reference

Arguments and options

Return value

`compute.releaseUniqueTag()`

Example

API reference

Arguments and options

Return value

Shared call options

Related documentation