Modes

Every workspace runs in one of two modes: permanent or temporary. The mode controls auto-expiry, restart behavior, and network configuration defaults.

Permanent mode

Permanent workspaces are designed to run continuously. They auto-restart on failure and have no time limit.

const workspace = await ws.create({
  image: 'node-20',
  mode: 'permanent',
});

Characteristics:

• restart_policy is set to always
• No TTL - runs until you explicitly stop or delete
• Static internal IP assigned
• Survives host maintenance

Best for: Production services, long-running daemons, development environments, persistent sandboxes.

Convert to permanent

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

This:

1. Sets restart_policy to always
2. Clears any TTL
3. Assigns a static IP
4. Relaunches the VM with new settings

Temporary mode

Temporary workspaces auto-expire after a configurable time to live (TTL). They're designed for short-lived tasks.

const workspace = await ws.create({
  image: 'python-3.12',
  mode: 'temporary',
  config: {
    ttl: '1h',
    ttl_action: 'stop',
    remove_on_exit: false,
  },
});

Characteristics:

• Auto-expires when TTL elapses
• Configurable action on expiry: stop or remove
• Optional auto-delete when VM exits
• Dynamic internal IP

Best for: CI/CD jobs, code execution sandboxes, time-limited test environments, one-off tasks.

TTL format

TTL is specified as a duration string:

TTL actions

Keep-alive (ping)

Extend the TTL while a user is active:

// Renew the TTL
await ws.lifecycle.ping('ws_a1b2c3d4');

// Renew with a specific duration
await ws.lifecycle.ping('ws_a1b2c3d4', { ttl_seconds: 3600 });

Convert to temporary

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

Restart policies

Control what happens when the VM process exits:

await ws.create({
  image: 'node-20',
  config: {
    restart_policy: 'on-failure',
    max_restarts: 5,
  },
});

max_restarts limits the number of automatic restart attempts. Set to 0 for unlimited restarts.

Auto-delete on exit

The remove_on_exit flag automatically deletes the workspace when the VM exits for any reason:

await ws.create({
  image: 'python-3.12',
  config: {
    ttl: '5m',
    remove_on_exit: true,
    cmd: ['python3', 'script.py'],
  },
});
// Workspace auto-deletes after script.py finishes or TTL expires

This is ideal for fire-and-forget execution where you don't need the workspace afterward.

Comparison

Switching modes

You can switch between modes at any time:

// Permanent → Temporary
await ws.lifecycle.makeTemporary(id, { ttl: '1h' });

// Temporary → Permanent
await ws.lifecycle.makePermanent(id);

// Just update the TTL
await ws.lifecycle.updateTTL(id, { ttl: '2h' });

Mode changes take effect immediately and relaunch the VM with the new configuration.