Workloads

Workloads are managed background processes running inside your workspace. Each workload has its own lifecycle (start/stop), logging, and status tracking.

Create

Create and start a new workload.

const workload = await ws.workloads.create('ws_a1b2c3d4', {
  cmd: ['node', 'server.js'],
  name: 'web-server',
  labels: { role: 'api', env: 'production' },
});

POST /workspace/:workspaceId/workloads

{
  "cmd": ["node", "server.js"],
  "name": "web-server",
  "labels": { "role": "api", "env": "production" }
}

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": ["node", "server.js"],
    "name": "web-server",
    "labels": { "role": "api" }
  }'

Parameters

Parameter	Type	Required	Description
`cmd`	`string[]`	Yes	Command array (non-empty)
`command`	`string[]`	-	Alias for `cmd`
`name`	`string`	No	Human-readable workload name
`labels`	`object`	No	Key-value labels for filtering

Response `201`

{
  "success": true,
  "workload": {
    "id": "wl_xyz789",
    "name": "web-server",
    "command": ["node", "server.js"],
    "labels": { "role": "api", "env": "production" },
    "state": "running",
    "created_at": "2026-02-24T10:30:00Z"
  }
}

List

List all workloads. Supports filtering by state, name, and labels.

const workloads = await ws.workloads.list('ws_a1b2c3d4', {
  states: 'running',
  name: 'web',
});

GET /workspace/:workspaceId/workloads?states=running&name=web

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads?states=running" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Parameter	Type	Description
`states`	`string`	Filter by state (e.g., `"running"`, `"stopped"`)
`name`	`string`	Filter by name (partial match)
`label_*`	`string`	Filter by label. e.g., `label_role=api`

Get

Get a specific workload.

const workload = await ws.workloads.get('ws_a1b2c3d4', 'wl_xyz789');

GET /workspace/:workspaceId/workloads/:workloadId

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Update

Update a workload's configuration.

await ws.workloads.update('ws_a1b2c3d4', 'wl_xyz789', {
  name: 'web-server-v2',
  labels: { version: '2.0' },
});

PUT /workspace/:workspaceId/workloads/:workloadId

{
  "name": "web-server-v2",
  "labels": { "version": "2.0" }
}

curl -X PUT "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-server-v2" }'

Delete

Delete a specific workload.

await ws.workloads.delete('ws_a1b2c3d4', 'wl_xyz789');

DELETE /workspace/:workspaceId/workloads/:workloadId

curl -X DELETE "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Delete all

Delete all workloads in the workspace.

await ws.workloads.deleteAll('ws_a1b2c3d4');

DELETE /workspace/:workspaceId/workloads

curl -X DELETE "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Start

Start a stopped workload.

await ws.workloads.start('ws_a1b2c3d4', 'wl_xyz789');

POST /workspace/:workspaceId/workloads/:workloadId/start

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789/start" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Stop

Stop a running workload.

await ws.workloads.stop('ws_a1b2c3d4', 'wl_xyz789');

POST /workspace/:workspaceId/workloads/:workloadId/stop

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789/stop" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Status

Get the current status of a workload.

const status = await ws.workloads.status('ws_a1b2c3d4', 'wl_xyz789');

GET /workspace/:workspaceId/workloads/:workloadId/status

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789/status" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Logs

Get logs for a workload.

const logs = await ws.workloads.logs('ws_a1b2c3d4', 'wl_xyz789');

GET /workspace/:workspaceId/workloads/:workloadId/logs

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789/logs" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Stream logs

Stream workload logs in real-time via SSE (Server-Sent Events).

const stream = await ws.workloads.streamLogs('ws_a1b2c3d4', 'wl_xyz789');

stream.on('data', (line) => console.log(line));
stream.on('end', () => console.log('Stream ended'));

GET /workspace/:workspaceId/workloads/:workloadId/logs/stream

Returns an SSE stream with 15-second heartbeat. Initial comment: :ok\n\n

:ok

data: {"line":"Server started on port 3000","timestamp":"2026-02-24T10:30:01Z"}

data: {"line":"GET / 200 12ms","timestamp":"2026-02-24T10:30:05Z"}

curl -N "https://api.oblien.com/workspace/ws_a1b2c3d4/workloads/wl_xyz789/logs/stream" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Close the connection to stop streaming.

On this page