> ## 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.

# Create and manage compute instances

> Create, inspect, list, extend, suspend, wake, and destroy Namespace compute instances with the TypeScript SDK.

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:

```typescript theme={null}
import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();
```

See [Compute Client](/docs/reference/typescript-sdk/compute/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.

<h3 id="compute-createinstance-example">
  Example
</h3>

Create an instance with a 30-minute deadline:

<Tabs>
  <Tab title="Linux">
    ```typescript theme={null}
    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](/docs/architecture/compute/machine-shapes#linux-configurations) for supported CPU and memory configurations.
  </Tab>

  <Tab title="macOS">
    ```typescript theme={null}
    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](/docs/architecture/compute/machine-shapes#macos-configurations) for supported CPU and memory configurations, and [macOS base image selection](/docs/architecture/compute/macos#base-image-selection) for available selectors.
  </Tab>

  <Tab title="Windows">
    ```typescript theme={null}
    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](/docs/architecture/compute/machine-shapes#windows-configurations) for supported CPU and memory configurations.
  </Tab>

  <Tab title="Linux on Apple Silicon">
    ```typescript theme={null}
    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](/docs/architecture/compute/machine-shapes#linux-on-apple-silicon) for supported CPU and memory configurations.
  </Tab>
</Tabs>

<h3 id="compute-createinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
createInstance(
  request: MessageInitShape<typeof CreateInstanceRequestSchema>,
  options?: CallOptions,
): Promise<DescribeInstanceResponse>
```

<h4 id="compute-createinstance-arguments-and-options">
  Arguments and options
</h4>

`createInstance()` accepts a `CreateInstanceRequest`. Common fields include:

<ResponseField name="shape" type="InstanceShape" required>
  CPU, memory, architecture, operating system, and optional platform selectors for the instance.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="virtualCpu" type="number" required>
      Number of virtual CPUs.
    </ResponseField>

    <ResponseField name="memoryMegabytes" type="number" required>
      Memory allocated to the instance, in megabytes.
    </ResponseField>

    <ResponseField name="machineArch" type="string">
      Machine architecture, such as `amd64` or `arm64`.
    </ResponseField>

    <ResponseField name="os" type="string">
      Operating system, such as `linux`, `macos`, or `windows`.
    </ResponseField>

    <ResponseField name="selectors" type="Label[]">
      Additional platform constraints, such as a macOS version.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="documentedPurpose" type="string">
  A human-readable description used to identify and debug the workload.
</ResponseField>

<ResponseField name="deadline" type="Timestamp">
  When Namespace should release the instance. Workspace policy can shorten the requested deadline.
</ResponseField>

<ResponseField name="placement" type="string[]">
  Ordered placement selectors such as `site:iad2`, `continent:us`, or `any`. When omitted, Namespace selects capacity for the workload.
</ResponseField>

<ResponseField name="labels" type="Label[]">
  Labels attached to the instance. You can use labels to filter instances when listing them.
</ResponseField>

<ResponseField name="containers" type="ContainerRequest[]">
  Containers to start during instance creation. Containers are supported on Linux instances.
</ResponseField>

<ResponseField name="applications" type="ApplicationRequest[]">
  Applications to start directly on the instance without containerization.
</ResponseField>

<ResponseField name="volumes" type="VolumeRequest[]">
  Persistent or cache volumes to attach to the instance.
</ResponseField>

The request also supports registry credentials, workload permissions, network policy, callbacks, and feature configuration. See the complete [`CreateInstanceRequest`](https://buf.build/namespace/cloud/docs/main:namespace.cloud.compute.v1beta#namespace.cloud.compute.v1beta.CreateInstanceRequest) API reference.

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-createinstance-return-value">
  Return value
</h4>

`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`](https://buf.build/namespace/cloud/docs/main:namespace.cloud.compute.v1beta#namespace.cloud.compute.v1beta.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`.

<h3 id="compute-createinstance-more-examples">
  More examples
</h3>

#### Start a container during creation

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

```typescript theme={null}
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:

```typescript theme={null}
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.

<h3 id="compute-waitinstance-example">
  Example
</h3>

Wait for the instance with a 10-minute timeout:

```typescript {1-4} theme={null}
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:

```typescript {1} theme={null}
for await (const update of client.compute.waitInstance({ instanceId })) {
  console.log(update.metadata?.status);
}
```

<h3 id="compute-waitinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
waitInstanceSync(
  request: MessageInitShape<typeof WaitInstanceRequestSchema>,
  options?: CallOptions,
): Promise<WaitInstanceResponse>

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

<h4 id="compute-waitinstance-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The instance to wait for.
</ResponseField>

<ResponseField name="destroyedOk" type="boolean">
  When `true`, the call does not fail if the instance is destroyed while waiting.
</ResponseField>

<ResponseField name="containerId" type="string">
  Wait for a specific container, identified by the Namespace-allocated container ID.
</ResponseField>

<ResponseField name="containerName" type="string">
  Wait for a specific container by the name given in `ContainerRequest.name`. When both `containerId` and `containerName` are set, `containerName` takes precedence.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-waitinstance-return-value">
  Return value
</h4>

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()`.

<h3 id="compute-startcontainers-example">
  Example
</h3>

```typescript {1-9} theme={null}
const { containers } = await client.compute.startContainers({
  instanceId,
  containers: [
    {
      name: "nginx",
      imageRef: "nginx",
    },
  ],
});

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

<h3 id="compute-startcontainers-api-reference">
  API reference
</h3>

```typescript theme={null}
startContainers(
  request: MessageInitShape<typeof StartContainersRequestSchema>,
  options?: CallOptions,
): Promise<StartContainersResponse>
```

<h4 id="compute-startcontainers-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The running instance to add containers to.
</ResponseField>

<ResponseField name="containers" type="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`](https://buf.build/namespace/cloud/docs/main:namespace.cloud.compute.v1beta#namespace.cloud.compute.v1beta.ContainerRequest) API reference.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-startcontainers-return-value">
  Return value
</h4>

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`.

<Info>
  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.
</Info>

## `compute.describeInstance()`

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

<h3 id="compute-describeinstance-example">
  Example
</h3>

```typescript {1} theme={null}
const described = await client.compute.describeInstance({ instanceId });

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

<h3 id="compute-describeinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
describeInstance(
  request: MessageInitShape<typeof DescribeInstanceRequestSchema>,
  options?: CallOptions,
): Promise<DescribeInstanceResponse>
```

<h4 id="compute-describeinstance-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The instance to describe.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-describeinstance-return-value">
  Return value
</h4>

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.

<h3 id="compute-listinstances-example">
  Example
</h3>

```typescript {1-4} theme={null}
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:

```typescript {3} theme={null}
const first = await client.compute.listInstances({ maxEntries: 20n });

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

<h3 id="compute-listinstances-api-reference">
  API reference
</h3>

```typescript theme={null}
listInstances(
  request: MessageInitShape<typeof ListInstancesRequestSchema>,
  options?: CallOptions,
): Promise<ListInstancesResponse>
```

<h4 id="compute-listinstances-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="maxEntries" type="bigint">
  The maximum number of entries to return. The service returns no more than `maxEntries`, and may return fewer.
</ResponseField>

<ResponseField name="paginationCursor" type="Uint8Array">
  The `paginationCursor` from a previous response. Continues reading results with the arguments of the original call.
</ResponseField>

<ResponseField name="includeCompleteRuns" type="boolean">
  When `true`, also includes instances in the `DESTROYED` and `ERROR` states.
</ResponseField>

<ResponseField name="notOlderThan" type="Timestamp">
  Excludes instances created before this timestamp, in UTC.
</ResponseField>

<ResponseField name="labelFilter" type="LabelFilterEntry[]">
  Only returns instances that match the specified labels.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-listinstances-return-value">
  Return value
</h4>

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.

<h3 id="compute-extendinstance-example">
  Example
</h3>

```typescript {3-6} theme={null}
import { durationFromMs } from "@bufbuild/protobuf/wkt";

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

console.log(extended.newDeadline);
```

<h3 id="compute-extendinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
extendInstance(
  request: MessageInitShape<typeof ExtendInstanceRequestSchema>,
  options?: CallOptions,
): Promise<ExtendInstanceResponse>
```

<h4 id="compute-extendinstance-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The instance to extend.
</ResponseField>

<ResponseField name="extendBy" type="Duration">
  The duration to extend the instance by.
</ResponseField>

<ResponseField name="ensureMinimum" type="Duration">
  The minimum duration the instance should keep running.
</ResponseField>

<ResponseField name="newDeadline" type="Timestamp">
  The new deadline, in UTC, at which the instance is destroyed.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-extendinstance-return-value">
  Return value
</h4>

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.

<h3 id="compute-suspendinstance-example">
  Example
</h3>

```typescript {1} theme={null}
await client.compute.suspendInstance({ instanceId });
```

<h3 id="compute-suspendinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
suspendInstance(
  request: MessageInitShape<typeof SuspendInstanceRequestSchema>,
  options?: CallOptions,
): Promise<Empty>
```

<h4 id="compute-suspendinstance-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The instance to suspend.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-suspendinstance-return-value">
  Return value
</h4>

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.

<h3 id="compute-wakeinstance-example">
  Example
</h3>

```typescript {1} theme={null}
await client.compute.wakeInstance({ instanceId });
```

<h3 id="compute-wakeinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
wakeInstance(
  request: MessageInitShape<typeof WakeInstanceRequestSchema>,
  options?: CallOptions,
): Promise<Empty>
```

<h4 id="compute-wakeinstance-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The instance to wake.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-wakeinstance-return-value">
  Return value
</h4>

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.

<h3 id="compute-destroyinstance-example">
  Example
</h3>

```typescript {1-4} theme={null}
await client.compute.destroyInstance({
  instanceId,
  reason: "Work completed",
});
```

<h3 id="compute-destroyinstance-api-reference">
  API reference
</h3>

```typescript theme={null}
destroyInstance(
  request: MessageInitShape<typeof DestroyInstanceRequestSchema>,
  options?: CallOptions,
): Promise<Empty>
```

<h4 id="compute-destroyinstance-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="instanceId" type="string" required>
  The instance to destroy.
</ResponseField>

<ResponseField name="reason" type="string">
  A human-readable reason recorded with the request.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-destroyinstance-return-value">
  Return value
</h4>

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

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

***

## `compute.releaseUniqueTag()`

Release the instance ID currently associated with a unique tag.

<h3 id="compute-releaseuniquetag-example">
  Example
</h3>

```typescript {1-3} theme={null}
const { instanceId: released } = await client.compute.releaseUniqueTag({
  uniqueTag: "build-runner",
});

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

<h3 id="compute-releaseuniquetag-api-reference">
  API reference
</h3>

```typescript theme={null}
releaseUniqueTag(
  request: MessageInitShape<typeof ReleaseUniqueTagRequestSchema>,
  options?: CallOptions,
): Promise<ReleaseUniqueTagResponse>
```

<h4 id="compute-releaseuniquetag-arguments-and-options">
  Arguments and options
</h4>

<ResponseField name="uniqueTag" type="string" required>
  The unique tag to release.
</ResponseField>

<ResponseField name="ifInstanceId" type="StringMatcher">
  Only release the tag when the currently associated instance ID matches.
</ResponseField>

<ResponseField name="options" type="CallOptions">
  Cancellation, timeout, and header options. See [Shared call options](#shared-call-options).
</ResponseField>

<h4 id="compute-releaseuniquetag-return-value">
  Return value
</h4>

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`.

<Info>
  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.
</Info>

## Shared call options

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

<ResponseField name="options" type="CallOptions">
  Controls cancellation, timeout, and request headers.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="timeoutMs" type="number">
      The call timeout in milliseconds. Set to a value of `0` or less to disable the default timeout.
    </ResponseField>

    <ResponseField name="signal" type="AbortSignal">
      Cancels the call when the signal is aborted. A cancelled call raises an error with code `Canceled`.
    </ResponseField>

    <ResponseField name="headers" type="HeadersInit">
      Custom headers to send with the request.
    </ResponseField>

    <ResponseField name="onHeader" type="(headers: Headers) => void">
      Called when response headers are received.
    </ResponseField>
  </Expandable>
</ResponseField>

## Related documentation

<Columns cols={3}>
  <Card title="Compute Client" icon="plug" href="/docs/reference/typescript-sdk/compute/compute-client">
    Configure authentication, region, and transport.
  </Card>

  <Card title="Machine shapes" icon="cpu" href="/docs/architecture/compute/machine-shapes">
    Supported CPU, memory, and platform configurations.
  </Card>

  <Card title="Compute platform" icon="microchip" href="/docs/architecture/compute">
    Platforms, storage, networking, and instance access.
  </Card>
</Columns>