Pause & Resume Sandbox - Documentation

Sandbox persistence lets you pause a sandbox and resume it later with the same filesystem and memory state. This is useful for long-running agent tasks, interactive apps, and workflows that need to survive idle periods without keeping compute resources active.

Manual pause and resume

When a sandbox is paused:

Files created in the sandbox are preserved.
In-memory state is preserved, including running processes and variables.
Network connections are interrupted until the sandbox resumes.
The sandbox remains stored until you resume and kill it, or kill it while it is paused.

import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

await sandbox.commands.run('echo hello > /tmp/message.txt')
const sandboxId = sandbox.sandboxId
await sandbox.pause()

console.log('Sandbox paused', sandboxId)

const resumed = await novita.sandbox.connect(sandboxId)
const result = await resumed.commands.run('cat /tmp/message.txt')
console.log(result.stdout)

await resumed.kill()

from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

sandbox.commands.run("echo hello > /tmp/message.txt")
sandbox_id = sandbox.sandbox_id
sandbox.pause()

print('Sandbox paused', sandbox_id)

resumed = novita.sandbox.connect(sandbox_id)
result = resumed.commands.run("cat /tmp/message.txt")
print(result.stdout)

resumed.kill()

# Pause a running sandbox (alias: sandbox ps)
novita-sandbox-cli sandbox pause <sandboxID>

# Resume a paused sandbox (alias: sandbox rs)
novita-sandbox-cli sandbox resume <sandboxID>

Auto pause and resume

Use lifecycle settings when you want the sandbox to pause automatically after timeout and optionally resume when activity is detected.

import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.files.write('/home/user/hello.txt', 'hello from a paused sandbox')
await sandbox.pause()

const content = await sandbox.files.read('/home/user/hello.txt')
console.log(content)
console.log(`State after read: ${(await sandbox.getInfo()).state}`)

from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create(
    timeout=10 * 60,
    lifecycle={
        'on_timeout': 'pause',
        'auto_resume': True,
    },
)

sandbox.files.write('/home/user/hello.txt', 'hello from a paused sandbox')
sandbox.pause()

content = sandbox.files.read('/home/user/hello.txt')
print(content)
print(f'State after read: {sandbox.get_info().state}')

Web server example

Auto-resume works well for preview environments and web servers.

import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create({
  timeoutMs: 5 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.commands.run('python3 -m http.server 3000', { background: true })
const host = sandbox.getHost(3000)
console.log(`Preview URL: https://${host}`)

from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create(
    timeout=5 * 60,
    lifecycle={
        'on_timeout': 'pause',
        'auto_resume': True,
    },
)

sandbox.commands.run('python3 -m http.server 3000', background=True)
host = sandbox.get_host(3000)
print(f'Preview URL: https://{host}')

Last modified on August 5, 2026

⌘I