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

# Manage images

> Register, inspect, optimize, and manage images used by Devboxes and blueprints.

Register images for use by Devboxes and blueprints with `client.images`. Fetch image records, inspect runtime metadata, optimize images for a site, and delete registered versions.

## `images.register()`

Register an image reference under a name. Metadata that you omit is derived from the image by the service.

### Example

```typescript {4-10} theme={null}
import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient();
const image = await client.images.register({
  ref: "node:22",
  name: "acme-development",
  description: "Development toolchain",
  metadata: {
    workspaceDir: "/workspace",
    shell: "/bin/bash",
  },
});
```

### API reference

```typescript theme={null}
register(input: RegisterImageInput, options?: OperationOptions): Promise<Image>
```

#### Arguments and options

<ResponseField name="input" type="RegisterImageInput" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="ref" type="string" required>The source image reference.</ResponseField>
    <ResponseField name="name" type="string" required>The registered image name.</ResponseField>
    <ResponseField name="description" type="string">A description of the image.</ResponseField>
    <ResponseField name="metadata" type="ImageMetadata">Runtime metadata. See [Image metadata](#image-metadata).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="OperationOptions">Optional `signal` and `timeoutMs`.</ResponseField>

#### Return value

Returns the registered [`Image`](#image-fields).

***

## `images.get()`

Fetch a registered image using any supported selector.

### Example

```typescript theme={null}
const image = await client.images.get({ name: "acme-development" });
```

### API reference

```typescript theme={null}
get(selector: ImageSelector, options?: OperationOptions): Promise<Image>
```

#### Arguments and options

<ResponseField name="selector" type="ImageSelector" required>See [Image selectors](#image-selectors).</ResponseField>
<ResponseField name="options" type="OperationOptions">Optional `signal` and `timeoutMs`.</ResponseField>

#### Return value

Returns the matching [`Image`](#image-fields).

***

## `images.list()`

List one page of registered images. Built-in images are excluded by default.

### Example

```typescript theme={null}
const page = await client.images.list({ includeBuiltin: true });
```

### API reference

```typescript theme={null}
list(options?: ListImagesOptions): Promise<Page<Image>>
```

#### Arguments and options

<ResponseField name="options" type="ListImagesOptions">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="cursor" type="string">An opaque cursor returned by the previous page.</ResponseField>
    <ResponseField name="includeBuiltin" type="boolean">Includes built-in images. Defaults to `false`.</ResponseField>
    <ResponseField name="signal" type="AbortSignal">Cancels the operation when aborted.</ResponseField>
    <ResponseField name="timeoutMs" type="number">The operation timeout in milliseconds.</ResponseField>
  </Expandable>
</ResponseField>

#### Return value

Returns a `Page<Image>` with `items: Image[]` and an optional `nextCursor`.

***

## `images.iterate()`

Iterate through all registered images, fetching pages automatically.

### Example

```typescript {1-2} theme={null}
for await (const image of client.images.iterate()) {
  console.log(image.name, image.ref);
}
```

### API reference

```typescript theme={null}
iterate(options?: Omit<ListImagesOptions, "cursor">): AsyncIterableIterator<Image>
```

#### Arguments and options

Accepts `includeBuiltin`, `signal`, and `timeoutMs`. Iteration manages the cursor.

#### Return value

Returns an async iterator of [`Image`](#image-fields) objects.

***

## `images.inspect()`

Inspect the effective user, environment, version, and optimization state of an image.

### Example

```typescript {1} theme={null}
const inspection = await client.images.inspect("acme-development");
console.log(inspection.optimizedSites);
```

### API reference

```typescript theme={null}
inspect(selector: ImageSelector, options?: OperationOptions): Promise<ImageInspection>
```

#### Arguments and options

<ResponseField name="selector" type="ImageSelector" required>See [Image selectors](#image-selectors).</ResponseField>
<ResponseField name="options" type="OperationOptions">Optional `signal` and `timeoutMs`.</ResponseField>

A string containing `/`, `@`, or `:` is inspected directly as a full image reference. Other selectors are resolved to the registered image's `repository@digest` reference first.

#### Return value

<ResponseField name="user" type="string">The image's effective user.</ResponseField>
<ResponseField name="environment" type="Record<string, string>" required>The effective environment.</ResponseField>
<ResponseField name="optimizedKinds" type="string[]" required>The compute kinds for which this version is optimized.</ResponseField>
<ResponseField name="optimizedSites" type="string[]" required>The sites where this version is optimized.</ResponseField>
<ResponseField name="version" type="bigint" required>The inspected version.</ResponseField>
<ResponseField name="versionCreatedAt" type="Date">When the version was created.</ResponseField>

***

## `images.optimize()`

Optimize an image for faster Devbox startup at a site. This operation can take several minutes and resolves only after optimization completes.

### Example

```typescript {1-3} theme={null}
await client.images.optimize("acme-development", {
  site: "iad",
  onProgress: (phase) => console.log(`Optimization: ${phase}`),
});
```

### API reference

```typescript theme={null}
optimize(selector: ImageSelector, options?: OptimizeImageOptions): Promise<void>
```

#### Arguments and options

<ResponseField name="selector" type="ImageSelector" required>See [Image selectors](#image-selectors).</ResponseField>

<ResponseField name="options" type="OptimizeImageOptions">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="site" type="string">The target site. Defaults to `"iad"`.</ResponseField>
    <ResponseField name="onProgress" type="(status: &#x22;preparing&#x22; | &#x22;starting&#x22; | &#x22;baking&#x22;) => void">Receives coarse progress phases in the order reported by the service.</ResponseField>
    <ResponseField name="signal" type="AbortSignal">Cancels the operation when aborted.</ResponseField>
    <ResponseField name="timeoutMs" type="number">The operation timeout in milliseconds.</ResponseField>
  </Expandable>
</ResponseField>

#### Return value

The promise resolves after the service reports completion. It rejects with `ImageOptimizationError` when the service reports failure or closes the progress stream before completion. The failure message is available on the error.

***

## `images.delete()`

Delete a registered image version selected by reference, ID, name, or digest.

### Example

```typescript {1-3} theme={null}
await client.images.delete({
  digest: image.digest,
  version: image.version,
});
```

### API reference

```typescript theme={null}
delete(selector: ImageSelector, options?: OperationOptions): Promise<void>
```

#### Arguments and options

<ResponseField name="selector" type="ImageSelector" required>See [Image selectors](#image-selectors).</ResponseField>
<ResponseField name="options" type="OperationOptions">Optional `signal` and `timeoutMs`.</ResponseField>

#### Return value

The SDK resolves the selector before deleting the selected version. The promise resolves after deletion completes.

## Image selectors

```typescript theme={null}
type ImageSelector =
  | string
  | { id: string }
  | { name: string }
  | { digest: string; version?: bigint };
```

A string containing `@` selects the digest after the final `@`. Every other string is interpreted as an image name. Use an object selector for an ID or digest, or whenever you need to make the interpretation explicit. Add `version` to a digest selector to select a specific registered version.

## Image metadata

```typescript theme={null}
interface ImageMetadata {
  workspaceDir?: string;
  shell?: string;
  user?: string;
  privileged?: boolean;
  environment?: Record<string, string>;
  onCreate?: BlueprintOperation[];
  onStart?: BlueprintOperation[];
  sessions?: BlueprintSession[];
  includeInPath?: string[];
}
```

<ResponseField name="workspaceDir" type="string">The default workspace directory.</ResponseField>
<ResponseField name="shell" type="string">The default shell executable.</ResponseField>
<ResponseField name="user" type="string">The remote user.</ResponseField>
<ResponseField name="privileged" type="boolean">Whether Devboxes use privileged mode. Defaults to `false` when explicitly supplied as metadata.</ResponseField>
<ResponseField name="environment" type="Record<string, string>">Environment variables included in the image configuration.</ResponseField>
<ResponseField name="onCreate" type="BlueprintOperation[]">Operations run when a Devbox is created.</ResponseField>
<ResponseField name="onStart" type="BlueprintOperation[]">Operations run when a Devbox starts.</ResponseField>
<ResponseField name="sessions" type="BlueprintSession[]">Named commands made available as sessions.</ResponseField>
<ResponseField name="includeInPath" type="string[]">Directories added to `PATH`.</ResponseField>

Operations and sessions have these forms:

```typescript theme={null}
type BlueprintOperation =
  | { command: string; args?: string[] }
  | { script: string };

interface BlueprintSession {
  name: string;
  command: string;
  emoji?: string;
}
```

Command operations execute a command with structured arguments. Script operations run shell source. A session requires a name and command, with an optional emoji.

## Image fields

<ResponseField name="id" type="string" required>The registered image ID.</ResponseField>
<ResponseField name="name" type="string" required>The registered name.</ResponseField>
<ResponseField name="repository" type="string" required>The image repository.</ResponseField>
<ResponseField name="digest" type="string" required>The effective digest.</ResponseField>
<ResponseField name="originalDigest" type="string">The source digest when it differs from the effective digest.</ResponseField>
<ResponseField name="ref" type="string" required>The resolved `repository@digest` reference.</ResponseField>
<ResponseField name="version" type="bigint" required>The registered version.</ResponseField>
<ResponseField name="description" type="string">The image description.</ResponseField>
<ResponseField name="createdAt" type="Date">When the image was registered.</ResponseField>
<ResponseField name="expiresAt" type="Date">When the image expires.</ResponseField>
<ResponseField name="managed" type="boolean" required>Whether Namespace manages the image.</ResponseField>

## Related documentation

See [Use blueprints](/docs/reference/typescript-sdk/blueprints) to use registered images in reusable configurations and [Create and manage Devboxes](/docs/reference/typescript-sdk/devboxes) to create a Devbox from an image.