Lifecycle

Every Vibengine sandbox follows a well-defined lifecycle from creation to cleanup. Understanding this lifecycle helps you manage resources efficiently and build reliable applications.

Lifecycle States

A sandbox moves through these states:

  create()         timeout / kill()        (auto)
     │                    │                   │
     ▼                    ▼                   ▼
┌─────────┐        ┌───────────┐        ┌─────────┐
│ Creating │──────▶ │  Running  │──────▶ │ Stopped │
└─────────┘        └───────────┘        └─────────┘
                     │       ▲
                     │       │
                pause()   resume()
                     │       │
                     ▼       │
                   ┌──────────┐
                   │  Paused  │
                   └──────────┘

State	Description
Creating	Sandbox is being provisioned (typically < 1 second)
Running	Sandbox is active and accepting commands
Paused	Sandbox state is saved to disk; no compute is used
Stopped	Sandbox is terminated; all resources are released

Timeouts

Every running sandbox has an associated timeout. When the timeout expires, the sandbox is automatically stopped and its resources are released.

Default Timeout

The default timeout is 60 seconds from sandbox creation.

import { Sandbox } from 'vibengine'

// This sandbox will automatically stop after 60 seconds
const sandbox = await Sandbox.create()

from vibengine import Sandbox

# This sandbox will automatically stop after 60 seconds
sandbox = Sandbox.create()

Custom Timeout

Set a custom timeout at creation time. The maximum timeout is 24 hours (86,400 seconds).

import { Sandbox } from 'vibengine'

// 5-minute timeout
const sandbox = await Sandbox.create({
  timeoutMs: 5 * 60 * 1000,
})

// 1-hour timeout
const longSandbox = await Sandbox.create({
  timeoutMs: 60 * 60 * 1000,
})

from vibengine import Sandbox

# 5-minute timeout
sandbox = Sandbox.create(timeout=5 * 60)

# 1-hour timeout
long_sandbox = Sandbox.create(timeout=60 * 60)

Extending the Timeout with keepAlive

You can extend a sandbox's timeout while it is running using keepAlive(). This resets the timeout countdown.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  timeoutMs: 60 * 1000, // 1 minute
})

// ... do some work ...

// Extend the timeout by another 5 minutes
await sandbox.keepAlive(5 * 60 * 1000)

// The sandbox now has 5 minutes remaining from this point
console.log('Timeout extended')

from vibengine import Sandbox

sandbox = Sandbox.create(timeout=60)  # 1 minute

# ... do some work ...

# Extend the timeout by another 5 minutes
sandbox.keep_alive(5 * 60)

# The sandbox now has 5 minutes remaining from this point
print("Timeout extended")

keepAlive() sets a new timeout duration starting from the moment it is called. It does not add time to the existing remaining timeout.

Keeping a Sandbox Alive During Long Tasks

For long-running tasks, periodically call keepAlive() to prevent the sandbox from timing out.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  timeoutMs: 2 * 60 * 1000, // 2 minutes
})

// Set up a keep-alive interval
const keepAliveInterval = setInterval(async () => {
  await sandbox.keepAlive(2 * 60 * 1000)
  console.log('Timeout refreshed')
}, 60 * 1000) // Refresh every minute

// Run a long task
const result = await sandbox.commands.run('python3 /home/user/long_training.py')

// Clean up the interval
clearInterval(keepAliveInterval)

// Kill when done
await sandbox.kill()

import threading
from vibengine import Sandbox

sandbox = Sandbox.create(timeout=2 * 60)  # 2 minutes

# Set up a keep-alive timer
def refresh_timeout():
    sandbox.keep_alive(2 * 60)
    print("Timeout refreshed")

timer = threading.Timer(60, refresh_timeout)  # Refresh every minute
timer.start()

# Run a long task
result = sandbox.commands.run("python3 /home/user/long_training.py")

# Clean up the timer
timer.cancel()

# Kill when done
sandbox.kill()

Stopping a Sandbox

You can explicitly stop a sandbox at any time using kill(). This immediately terminates all processes and releases resources.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create({
  timeoutMs: 60 * 60 * 1000, // 1 hour
})

// Do some work
await sandbox.commands.run('echo "task complete"')

// Explicitly stop — don't wait for the 1-hour timeout
await sandbox.kill()
console.log('Sandbox stopped immediately')

from vibengine import Sandbox

sandbox = Sandbox.create(timeout=60 * 60)  # 1 hour

# Do some work
sandbox.commands.run('echo "task complete"')

# Explicitly stop — don't wait for the 1-hour timeout
sandbox.kill()
print("Sandbox stopped immediately")

Always call kill() when you are done with a sandbox. This frees resources immediately and avoids unnecessary charges for idle sandboxes waiting for their timeout.

Auto-Cleanup

Vibengine automatically manages sandbox cleanup:

Timeout expiry: When a sandbox's timeout expires, it is automatically stopped
Orphaned sandboxes: If a client disconnects without calling kill(), the sandbox continues running until its timeout expires
Resource reclamation: After a sandbox stops, its compute and (unless paused) storage resources are fully released

Lifecycle Best Practices

Set appropriate timeouts: Use short timeouts for quick tasks and longer timeouts for interactive sessions
Use keepAlive for long tasks: Periodically extend the timeout during long-running operations
Always kill when done: Call kill() explicitly rather than waiting for timeout
Use pause for persistence: If you need the state later, pause() instead of kill()
Handle disconnections: Store sandbox IDs so you can reconnect if your client disconnects

Lifecycle Events Summary

Action	Effect	State After
`Sandbox.create()`	Provisions a new sandbox	Running
`sandbox.keepAlive(ms)`	Resets the timeout countdown	Running
`sandbox.pause()`	Saves state, stops compute	Paused
`Sandbox.resume(id)`	Restores state, starts compute	Running
`sandbox.kill()`	Terminates immediately	Stopped
Timeout expires	Automatic termination	Stopped

Next Steps

Create a Sandbox — set timeout and other options at creation
Connect to a Sandbox — reconnect to running sandboxes
Persistence — pause and resume for long-term state
Metrics — monitor resources during the sandbox lifetime

Lifecycle

On this page