Persistence

By default, Vibengine sandboxes are ephemeral — when a sandbox stops, all filesystem changes and running processes are lost. However, you can use the pause and resume feature to persist sandbox state across sessions, allowing you to pick up exactly where you left off.

How Persistence Works

When you pause a sandbox:

The sandbox's entire filesystem state is captured and saved
The sandbox stops running and releases compute resources
You are not charged for compute while the sandbox is paused

When you resume a sandbox:

A new sandbox is provisioned with the saved filesystem state
All files and directories are restored exactly as they were
The sandbox is ready to use with a new timeout

Pausing saves the filesystem state only. Running processes, network connections, and in-memory state are not preserved. If you need a process running after resume, start it again after resuming.

Pausing a Sandbox

Pause a running sandbox to save its state for later.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Do some work — install packages, create files
await sandbox.commands.run('pip install pandas numpy')
await sandbox.files.write('/home/user/data.csv', 'name,value\nAlice,42\nBob,73')
await sandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"')

// Pause the sandbox to save state
const sandboxId = sandbox.sandboxId
await sandbox.pause()

console.log(`Sandbox ${sandboxId} paused. Resume it later.`)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Do some work — install packages, create files
sandbox.commands.run("pip install pandas numpy")
sandbox.files.write("/home/user/data.csv", "name,value\nAlice,42\nBob,73")
sandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"')

# Pause the sandbox to save state
sandbox_id = sandbox.sandbox_id
sandbox.pause()

print(f"Sandbox {sandbox_id} paused. Resume it later.")

Resuming a Sandbox

Resume a previously paused sandbox to restore its state.

import { Sandbox } from 'vibengine'

// Resume the paused sandbox
const sandbox = await Sandbox.resume(sandboxId)

// Everything is restored — packages are still installed
const result = await sandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"')
console.log(result.stdout) // The version number prints correctly

// Files are still there
const data = await sandbox.files.read('/home/user/data.csv')
console.log(data) // "name,value\nAlice,42\nBob,73"

from vibengine import Sandbox

# Resume the paused sandbox
sandbox = Sandbox.resume(sandbox_id)

# Everything is restored — packages are still installed
result = sandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"')
print(result.stdout)  # The version number prints correctly

# Files are still there
data = sandbox.files.read("/home/user/data.csv")
print(data)  # "name,value\nAlice,42\nBob,73"

Resume with New Options

When resuming, you can specify a new timeout and other options.

import { Sandbox } from 'vibengine'

// Resume with a longer timeout
const sandbox = await Sandbox.resume(sandboxId, {
  timeoutMs: 30 * 60 * 1000, // 30 minutes
})

console.log('Resumed with 30-minute timeout')

from vibengine import Sandbox

# Resume with a longer timeout
sandbox = Sandbox.resume(sandbox_id, timeout=30 * 60)  # 30 minutes

print("Resumed with 30-minute timeout")

Full Pause/Resume Workflow

A typical pattern for building persistent coding environments.

import { Sandbox } from 'vibengine'

// --- Session 1: Initial setup ---
async function setupEnvironment(userId) {
  const sandbox = await Sandbox.create({
    timeoutMs: 10 * 60 * 1000,
    metadata: { userId },
  })

  // Heavy setup that takes time
  await sandbox.commands.run('apt-get update && apt-get install -y build-essential')
  await sandbox.commands.run('pip install torch transformers datasets')
  await sandbox.files.write('/home/user/config.yaml', 'model: gpt2\nbatch_size: 32')

  // Save state for later
  const sandboxId = sandbox.sandboxId
  await sandbox.pause()

  // Store sandboxId in your database
  await db.save({ userId, sandboxId })

  return sandboxId
}

// --- Session 2: Continue work ---
async function continueWork(userId) {
  const record = await db.findByUserId(userId)
  const sandbox = await Sandbox.resume(record.sandboxId, {
    timeoutMs: 10 * 60 * 1000,
  })

  // All packages and files are ready — no reinstallation needed
  const result = await sandbox.commands.run('python3 -c "import torch; print(torch.__version__)"')
  console.log('PyTorch version:', result.stdout.trim())

  // Do more work...
  await sandbox.commands.run('python3 /home/user/train.py')

  // Pause again when done
  await sandbox.pause()
}

from vibengine import Sandbox

# --- Session 1: Initial setup ---
def setup_environment(user_id: str) -> str:
    sandbox = Sandbox.create(
        timeout=10 * 60,
        metadata={"user_id": user_id},
    )

    # Heavy setup that takes time
    sandbox.commands.run("apt-get update && apt-get install -y build-essential")
    sandbox.commands.run("pip install torch transformers datasets")
    sandbox.files.write("/home/user/config.yaml", "model: gpt2\nbatch_size: 32")

    # Save state for later
    sandbox_id = sandbox.sandbox_id
    sandbox.pause()

    # Store sandbox_id in your database
    db.save(user_id=user_id, sandbox_id=sandbox_id)

    return sandbox_id

# --- Session 2: Continue work ---
def continue_work(user_id: str):
    record = db.find_by_user_id(user_id)
    sandbox = Sandbox.resume(
        record.sandbox_id,
        timeout=10 * 60,
    )

    # All packages and files are ready — no reinstallation needed
    result = sandbox.commands.run('python3 -c "import torch; print(torch.__version__)"')
    print("PyTorch version:", result.stdout.strip())

    # Do more work...
    sandbox.commands.run("python3 /home/user/train.py")

    # Pause again when done
    sandbox.pause()

Paused sandboxes consume storage for their saved filesystem state. Remember to clean up paused sandboxes you no longer need by calling kill() instead of pause().

Ephemeral vs. Persistent Sandboxes

Feature	Ephemeral (default)	Persistent (pause/resume)
State after stop	Lost	Saved to disk
Compute cost while stopped	None	None
Storage cost while stopped	None	Yes (filesystem snapshot)
Startup time	Fast (from template)	Fast (from snapshot)
Best for	One-off tasks	Multi-session workflows

Next Steps

Sandbox Lifecycle — understand the full sandbox lifecycle
Create a Sandbox — sandbox creation options
Metrics — monitor resource usage

Persistence

On this page