Images

Browse the catalog of base images available for creating workspaces — operating systems, language runtimes, databases and a few ready-made environments, each built with a full userland (see Concepts: Images).

The value you pass to create({ image }) is the entry's image field (a Docker reference such as oblien/node:24), not its id. Any public Docker image works too; the catalog is curated, not a whitelist.

Some entries also have a preset field. Pass that value to create({ preset }) to include the entry's shared software and boot setup. For example, Xcode 26.6 uses the same macOS base as the ordinary Mac entry and adds a read-only software disk. Passing only its image creates the base environment without those tools.

const { images } = await client.workspaces.images.list({ search: 'xcode' });
const selected = images.find(image => image.preset);
const workspace = await client.workspaces.create({
  preset: selected!.preset,
  name: 'ios-development',
  ready_timeout_seconds: 1800,
});

Preset entries expose base_image, revision, software, resource defaults and minimums, and boot workload/readiness metadata. The server resolves these fields; submit the preset ID, not a copied disk ID or boot command. CPU, RAM, writable disk, namespace and optional desktop access use the normal creation settings. Existing workspaces keep their resolved selection when a preset is updated.

Catalog entries also expose base_os, for example { "family": "linux", "distribution": "ubuntu", "version": "24.04" } or { "family": "macos", "distribution": "macos", "version": "26.6.2" }. The workspace Software library uses this metadata to show compatible tools. Desktop choices belong to the Desktop panel, without separate desktop image cards.

List images

Search and browse available images.

// All images
const all = await ws.images.list();

// Search by keyword
const nodeImages = await ws.images.list({ search: 'node' });

// Filter by category
const databases = await ws.images.list({ category: 'database' });

GET /workspace/images?search=node&category=runtime

# All images
curl "https://api.oblien.com/workspace/images" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# Search
curl "https://api.oblien.com/workspace/images?search=python" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# By category
curl "https://api.oblien.com/workspace/images?category=database" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Response

{
  "images": [
    {
      "id": "ubuntu-2404",
      "label": "Ubuntu 24.04 LTS",
      "desc": "The default machine — Ubuntu 24.04 with networking, debugging, git and build tools ready",
      "category": "os",
      "image": "oblien/ubuntu:24.04",
      "base_os": { "family": "linux", "distribution": "ubuntu", "version": "24.04" },
      "logo": "https://cdn.simpleicons.org/ubuntu/E95420",
      "color": "#E95420",
      "recommended": true,
      "includes": ["apt", "git", "curl/wget", "ssh", "ping/dig/ss", "build-essential", "python3"]
    },
    {
      "id": "postgres",
      "label": "PostgreSQL 18",
      "desc": "Postgres 18 with pgvector — relational, JSONB, full-text and vector search in one server",
      "category": "database",
      "image": "oblien/postgres:18",
      "logo": "https://cdn.simpleicons.org/postgresql/4169E1",
      "color": "#4169E1",
      "recommended": true,
      "includes": ["PostgreSQL 18", "pgvector", "psql", "pg_dump/pg_restore"],
      "env": [
        { "key": "POSTGRES_PASSWORD", "desc": "Superuser password", "required": true, "default": "postgres" },
        { "key": "POSTGRES_USER", "desc": "Superuser name (default: postgres)", "required": false }
      ]
    }
  ],
  "categories": [
    { "id": "all", "label": "All" },
    { "id": "os", "label": "Operating Systems" },
    { "id": "database", "label": "Databases" }
  ]
}

Response fields

Available images

Roughly two dozen entries across os, devtools, runtime, ai, browser, database and infra. Rather than duplicating the list here, browse it live — it is versioned and moves when the underlying runtimes release.

See Concepts: Images for how to choose one, what every image ships with, and what to use in place of a retired entry.

macOS images

Use image: "oblien/macos-tahoe:26.6.2". Internal build revisions such as R21 do not appear in image names returned by the catalog or workspace API. Each accepted creation pins its build internally, so a later release cannot change an existing workspace's shared base or writable layer.

An image's desktop field describes its optional desktop choice. Compatible images advertise desktop.installable, desktop.vm_defaults and desktop.minimum_resources; these defaults and minimums apply when desktop is selected. capabilities describes services already installed in that image.

Create with the ordinary image reference and config.desktop.enabled: true. desktop.prepared: true means setup can use a prepared environment; otherwise an installable image prepares its desktop during creation. Ubuntu uses a prepared environment; Debian 13 and Node.js 24 install lazily. macOS already includes its desktop, so the choice enables access. The recipe is an internal implementation detail; clients never supply installation commands or private artifact names. The option defaults off. CPU, RAM and writable disk still use the normal workspace resource fields. Workspace responses keep the public OS image name and expose installation metadata through image_desktop. image_capabilities describes the base image; live /desktop/status reports installed support.

The macOS Tahoe entry provides its KVM kernel, resource defaults, native agent and readiness settings through vm_defaults. Configure its networking and native boot behavior with config.macos. See remote desktop and macOS workspaces.