Lifecycle & Power

Control workspace power state and lifecycle mode. Workspaces can be permanent (persistent, optionally sleeping when idle) or temporary (auto-expire with TTL).

Sleep when idle

PUT /workspace/:workspaceId/lifecycle/idle accepts { suspend_after: "15m", stop_after: 0 }. Use { suspend_after: 0 } to disable automatic sleep. The minimum idle time is 120 seconds; an optional nonzero memory-retention limit must be at least one hour. GET /workspace/:workspaceId/lifecycle includes the normalized idle policy and snapshot_supported capability.

await ws.lifecycle.setIdle('ws_a1b2c3d4', { suspend_after: '15m' });
await ws.lifecycle.setIdle('ws_a1b2c3d4', null); // disable

The API rejects enabling this for temporary workspaces or those without memory snapshot support. All exposed port URLs and connected custom domains share the workspace policy and wake coordination. See Sleep and wake on request for setup, readiness, retries, keep-alives and memory retention.

While a power request is in progress, workspace reads and lists report info.status as starting, stopping, restarting, pausing, or resuming, with ready: false. The dashboard shows this status immediately, keeps it after a page refresh, and polls every two seconds while the page is visible until the operation settles.

Power methods still wait for the operation to finish, so existing await ws.start(...) and await ws.stop(...) calls work as before. A separate GET /workspace/:workspaceId can read progress during that wait. Use info.status for the transition; info.is_running describes the underlying VM process and may still be true while it shuts down.

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"

Reinstall

Reset the workspace to a fresh install of its base image, keeping the workspace itself.

Use this when a workspace has been broken or cluttered beyond repair and you want to start over without losing its identity — the same workspace ID, URLs and settings keep working.

Destructive and irreversible. Everything written inside the workspace is permanently deleted, including installed packages, changes to /root and /etc, and the contents of /workspace. There is no undo and no automatic backup. To keep anything, create an archive first.

Kept: workspace ID, IP address, hostname and public URLs, custom domains, image, CPU/memory/disk, network policy and ingress ports, metadata.

Reset: the entire filesystem, back to the base image. SSH is also switched off, because openssh-server lived in the erased filesystem — enable SSH again afterwards if you need it.

await ws.reinstall('ws_a1b2c3d4');

POST /workspace/:workspaceId/reinstall

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

Response

{
  "success": true,
  "workspace_id": "ws_a1b2c3d4",
  "reinstalled": true,
  "running": true,
  "ip": "10.103.0.131",
  "message": "Sandbox reinstalled: filesystem reset to the base image, same workspace id, IP and settings."
}

Response fields

Field	Description
`reinstalled`	`true` once the filesystem has been reset
`running`	Whether the workspace had reported running again before the call returned
`ip`	Unchanged — the workspace keeps its address

Errors

Code	Status	Meaning
`vm_missing`	409	The workspace has no VM to reset. It needs to be re-created rather than reinstalled.
`stop_failed`	502	The workspace could not be stopped, so nothing was reset. It is left as it was.
`overlay_delete_failed`	502	The filesystem could not be reset. Nothing was deleted and the workspace is started again.
`relaunch_failed`	502	The filesystem was reset but the workspace did not start again. Its data is already cleared; call start to finish the reinstall.

A reinstall boots from the workspace's stored settings, so any change you made since it last started — resources, network policy, ingress ports — is applied by the reinstall.

Learn more about lifecycle modes in Concepts: Modes.

On this page