Manage images - Namespace Documentation

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

Example

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

register(input: RegisterImageInput, options?: OperationOptions): Promise<Image>

Arguments and options

RegisterImageInput

required

Hide properties

string

required

The source image reference.

string

required

The registered image name.

string

A description of the image.

ImageMetadata

Runtime metadata. See Image metadata.

OperationOptions

Optional signal and timeoutMs.

Return value

Returns the registered Image.

`images.get()`

Fetch a registered image using any supported selector.

Example

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

API reference

get(selector: ImageSelector, options?: OperationOptions): Promise<Image>

Arguments and options

ImageSelector

required

See Image selectors.

OperationOptions

Optional signal and timeoutMs.

Return value

Returns the matching Image.

`images.list()`

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

Example

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

API reference

list(options?: ListImagesOptions): Promise<Page<Image>>

Arguments and options

ListImagesOptions

Hide properties

string

An opaque cursor returned by the previous page.

boolean

Includes built-in images. Defaults to false.

AbortSignal

Cancels the operation when aborted.

number

The operation timeout in milliseconds.

Return value

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

`images.iterate()`

Iterate through all registered images, fetching pages automatically.

Example

for await (const image of client.images.iterate()) {
  console.log(image.name, image.ref);
}

API reference

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

`images.inspect()`

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

Example

const inspection = await client.images.inspect("acme-development");
console.log(inspection.optimizedSites);

API reference

inspect(selector: ImageSelector, options?: OperationOptions): Promise<ImageInspection>

Arguments and options

ImageSelector

required

See Image selectors.

OperationOptions

Optional signal and timeoutMs.

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

string

The image’s effective user.

Record<string, string>

required

The effective environment.

string[]

required

The compute kinds for which this version is optimized.

string[]

required

The sites where this version is optimized.

bigint

required

The inspected version.

Date

When the version was created.

`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

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

API reference

optimize(selector: ImageSelector, options?: OptimizeImageOptions): Promise<void>

Arguments and options

ImageSelector

required

See Image selectors.

OptimizeImageOptions

Hide properties

string

The target site. Defaults to "iad".

(status: "preparing" | "starting" | "baking") => void

Receives coarse progress phases in the order reported by the service.

AbortSignal

Cancels the operation when aborted.

number

The operation timeout in milliseconds.

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

await client.images.delete({
  digest: image.digest,
  version: image.version,
});

API reference

delete(selector: ImageSelector, options?: OperationOptions): Promise<void>

Arguments and options

ImageSelector

required

See Image selectors.

OperationOptions

Optional signal and timeoutMs.

Return value

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

Image selectors

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

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

string

The default workspace directory.

string

The default shell executable.

string

The remote user.

boolean

Whether Devboxes use privileged mode. Defaults to false when explicitly supplied as metadata.

Record<string, string>

Environment variables included in the image configuration.

BlueprintOperation[]

Operations run when a Devbox is created.

BlueprintOperation[]

Operations run when a Devbox starts.

BlueprintSession[]

Named commands made available as sessions.

string[]

Directories added to PATH.

Operations and sessions have these forms:

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

string

required

The registered image ID.

string

required

The registered name.

string

required

The image repository.

string

required

The effective digest.

string

The source digest when it differs from the effective digest.

string

required

The resolved repository@digest reference.

bigint

required

The registered version.

string

The image description.

Date

When the image was registered.

Date

When the image expires.

boolean

required

Whether Namespace manages the image.

See Use blueprints to use registered images in reusable configurations and Create and manage Devboxes to create a Devbox from an image.

​images.register()

​Example

​API reference

​Arguments and options

​Return value

​images.get()

​Example

​API reference

​Arguments and options

​Return value

​images.list()

​Example

​API reference

​Arguments and options

​Return value

​images.iterate()

​Example

​API reference

​Arguments and options

​Return value

​images.inspect()

​Example

​API reference

​Arguments and options

​Return value

​images.optimize()

​Example

​API reference

​Arguments and options

​Return value

​images.delete()

​Example

​API reference

​Arguments and options

​Return value

​Image selectors

​Image metadata

​Image fields

​Related documentation

`images.register()`

Example

API reference

Arguments and options

Return value

`images.get()`

Example

API reference

Arguments and options

Return value

`images.list()`

Example

API reference

Arguments and options

Return value

`images.iterate()`

Example

API reference

Arguments and options

Return value

`images.inspect()`

Example

API reference

Arguments and options

Return value

`images.optimize()`

Example

API reference

Arguments and options

Return value

`images.delete()`

Example

API reference

Arguments and options

Return value

Image selectors

Image metadata

Image fields

Related documentation