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"`, or `"unless-stopped"`
`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"`, `"pause"`, or `"remove"` — action on TTL expiry
`remove_on_exit`	`boolean`	Auto-delete on VM exit (temporary mode only)
`uptime`	`number`	Seconds since last start

Make permanent

Convert a workspace to permanent mode. Clears TTL, sets restart_policy (default "always"). Config-only — does not start or stop the VM.

// Default restart_policy = 'always'
const result = await ws.lifecycle.makePermanent('ws_a1b2c3d4');

// Or specify a restart policy
const result = await ws.lifecycle.makePermanent('ws_a1b2c3d4', {
  restart_policy: 'on-failure',
});

POST /workspace/:workspaceId/lifecycle/permanent

{ "restart_policy": "on-failure" }

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" \
  -H "Content-Type: application/json" \
  -d '{ "restart_policy": "always" }'

Parameters

Parameter	Type	Required	Default	Description
`restart_policy`	`string`	No	`"always"`	`"no"`, `"on-failure"`, `"always"`, or `"unless-stopped"`

Permanent mode means:

restart_policy configurable (default "always")
No TTL — workspace runs until you stop it
No ttl_action, no remove_on_exit
Static network IP assigned
Config applied hot — no VM restart needed

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\|number`	Yes	Duration string (e.g., `"30m"`, `"1h"`, `"24h"`) or seconds as number
`ttl_action`	`string`	No	`"stop"`, `"pause"`, or `"remove"`. Default: `"stop"`
`remove_on_exit`	`boolean`	No	Auto-delete when VM exits

restart_policy is always locked to "no" for temporary workspaces. The Go VM server enforces: TTL > 0 → restart_policy = "no". This parameter is not accepted on this endpoint.

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\|number`	New TTL duration (string or seconds)
`ttl_action`	`string`	`"stop"`, `"pause"`, or `"remove"`

restart_policy is not accepted — temporary workspaces are locked to "no". All changes are applied hot — no VM relaunch required.

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