Lifecycle & Power

Control workspace power state and lifecycle mode. Workspaces can be permanent (always running, auto-restart) or temporary (auto-expire with TTL).

Start

Start a stopped workspace.

await ws.start('ws_a1b2c3d4');

// Force start (skip state checks)
await ws.start('ws_a1b2c3d4', { force: true });

POST /workspace/:workspaceId/start

{ "force": true }

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

Parameters

Parameter	Type	Default	Description
`force`	`boolean`	`false`	Force start even if already running

Errors

Code	Status	Cause
`RUNNING_POOL_REACHED`	402	Running pool quota full - stop another workspace first
`VM_UNAVAILABLE`	503	VM backend is unreachable

Stop

Stop a running workspace. The VM is shut down but data is preserved.

await ws.stop('ws_a1b2c3d4');

POST /workspace/:workspaceId/stop

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

Restart

Stop and immediately restart the workspace.

await ws.restart('ws_a1b2c3d4');

POST /workspace/:workspaceId/restart

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

Pause

Freeze the workspace - all processes are suspended, memory state is preserved. No CPU is consumed while paused.

await ws.pause('ws_a1b2c3d4');

POST /workspace/:workspaceId/pause

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

Resume

Resume a paused workspace. Processes continue from where they were frozen.

await ws.resume('ws_a1b2c3d4');

POST /workspace/:workspaceId/resume

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

Get lifecycle

Get the current lifecycle configuration and status.

const lifecycle = await ws.lifecycle.get('ws_a1b2c3d4');

GET /workspace/:workspaceId/lifecycle

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

Response

{
  "success": true,
  "mode": "permanent",
  "status": "running",
  "restart_policy": "always",
  "max_restarts": 0,
  "restart_info": {},
  "ttl": null,
  "ttl_action": null,
  "remove_on_exit": false,
  "uptime": 7200
}

Response fields

Field	Type	Description
`mode`	`string`	`"permanent"` or `"temporary"`
`status`	`string`	Current VM status
`restart_policy`	`string`	`"no"`, `"always"`, `"on-failure"`
`max_restarts`	`number`	Max restart attempts (0 = unlimited)
`restart_info`	`object`	Current restart count and history
`ttl`	`string\|null`	Time to live (e.g., `"1h"`) - only for temporary mode
`ttl_action`	`string\|null`	`"stop"` or `"remove"` - action on TTL expiry
`remove_on_exit`	`boolean`	Auto-delete on VM exit
`uptime`	`number`	Seconds since last start

Make permanent

Convert a workspace to permanent mode. Sets restart_policy=always, clears TTL, and relaunches the VM.

const result = await ws.lifecycle.makePermanent('ws_a1b2c3d4');
// { success: true, mode: 'permanent', config: {...} }

POST /workspace/:workspaceId/lifecycle/permanent

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

Permanent mode means:

Static network IP assigned
restart_policy set to always
No TTL - workspace runs until you stop it
VM relaunched with new settings

Make temporary

Convert a workspace to temporary mode with a TTL.

const result = await ws.lifecycle.makeTemporary('ws_a1b2c3d4', {
  ttl: '1h',
  ttl_action: 'stop',
  remove_on_exit: false,
});

POST /workspace/:workspaceId/lifecycle/temporary

{
  "ttl": "1h",
  "ttl_action": "stop",
  "remove_on_exit": false
}

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/lifecycle/temporary" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": "1h", "ttl_action": "stop" }'

Parameters

Parameter	Type	Required	Description
`ttl`	`string`	Yes	Duration string (e.g., `"30m"`, `"1h"`, `"24h"`)
`ttl_action`	`string`	No	`"stop"` or `"remove"`. Default: `"stop"`
`remove_on_exit`	`boolean`	No	Auto-delete when VM exits

Update TTL

Change the TTL or TTL action on a temporary workspace without mode conversion.

await ws.lifecycle.updateTTL('ws_a1b2c3d4', {
  ttl: '2h',
  ttl_action: 'remove',
});

PUT /workspace/:workspaceId/lifecycle/ttl

{
  "ttl": "2h",
  "ttl_action": "remove"
}

curl -X PUT "https://api.oblien.com/workspace/ws_a1b2c3d4/lifecycle/ttl" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": "2h", "ttl_action": "remove" }'

Parameters

At least one field is required:

Parameter	Type	Description
`ttl`	`string`	New TTL duration
`ttl_action`	`string`	`"stop"` or `"remove"`

Ping

Keep-alive signal that renews the TTL on a temporary workspace. Use this to prevent auto-expiry while a user is active.

await ws.lifecycle.ping('ws_a1b2c3d4', {
  ttl_seconds: 3600,
});

POST /workspace/:workspaceId/ping

{ "ttl_seconds": 3600 }

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/ping" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ttl_seconds": 3600 }'

Parameters

Parameter	Type	Description
`ttl_seconds`	`number`	Optional. Override TTL renewal duration in seconds

Destroy

Forcefully destroy the workspace VM. This stops the VM and deletes it from the hypervisor. The workspace record remains in your account until you call delete.

await ws.lifecycle.destroy('ws_a1b2c3d4');

DELETE /workspace/:workspaceId/lifecycle

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

Learn more about lifecycle modes in Concepts: Modes.

On this page