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"

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