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.

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

Parameter	Type	Default	Description
`search`	`string`	-	Partial match on id, label, description, image reference, contents and keywords — so `laravel` finds the PHP image and `mysql` finds MariaDB
`category`	`string`	`"all"`	`"all"`, `"os"`, `"devtools"`, `"runtime"`, `"ai"`, `"browser"`, `"database"`, `"infra"`

This endpoint does not require workspace ownership. Any authenticated user can browse images.

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",
      "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

Field	Description
`id`	Stable key for the entry. Used for UI selection, not as the `image` value
`image`	The Docker reference to pass to `create({ image })`
`label` / `desc`	Display name and one-line summary
`category`	One of the ids in `categories`
`logo` / `color`	Icon URL and accent color; the same values appear on workspace rows as `image_logo` / `image_color`
`includes`	Headline contents of the image (not exhaustive)
`env`	Declared environment variables. An entry with `required: true` must be supplied in `config.env` or create fails with `MISSING_REQUIRED_ENV`
`recommended`	Suggested default for its row

env entries marked required exist for a reason: they are the images that either refuse to initialise without a password (Postgres, MariaDB) or would otherwise serve an unauthenticated port that can be published to a public URL (code-server, JupyterLab).

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.