Images

Browse the catalog of base images available for creating workspaces. Images come pre-configured with operating systems, runtimes, and databases.

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 image ID, label, or description
`category`	`string`	`"all"`	`"all"`, `"os"`, `"runtime"`, or `"database"`

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

Response

{
  "success": true,
  "images": [
    {
      "id": "node-20",
      "label": "Node.js 20",
      "description": "Node.js 20 LTS on Ubuntu",
      "category": "runtime"
    },
    {
      "id": "ubuntu-24",
      "label": "Ubuntu 24.04",
      "description": "Ubuntu 24.04 LTS",
      "category": "os"
    }
  ],
  "categories": ["os", "runtime", "database"]
}

Available images

Operating Systems

Image ID	Description
`ubuntu-22`	Ubuntu 22.04 LTS
`ubuntu-24`	Ubuntu 24.04 LTS
`debian-12`	Debian 12 (Bookworm)
`alpine-3`	Alpine Linux 3

Runtimes

Image ID	Description
`node-20`	Node.js 20 LTS
`node-22`	Node.js 22
`python-3.12`	Python 3.12
`python-3.13`	Python 3.13
`go-1.22`	Go 1.22
`rust-1`	Rust 1.x (latest stable)

Databases

Image ID	Description
`redis-7`	Redis 7
`postgres-16`	PostgreSQL 16

All images come with common tools pre-installed (curl, wget, git, vim, etc.). Choose the image closest to your use case to minimize setup time.

See Concepts: Images for more details on choosing and customizing images.

On this page