Skip to main content
These features build on Sandbox Persistence. Auto-pause keeps sandbox state when the maximum lifetime expires. Auto-resume wakes a paused sandbox when new work reaches it.

​
Configure

When creating a sandbox, pass a lifecycle configuration. This controls timeout behavior and whether a paused sandbox can wake automatically. 
import { Sandbox } from 'novita-sandbox'

const sandbox = await Sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true, // resume when activity arrives
  },
})

​
Lifecycle options

The lifecycle setting supports these fields:
SettingOptionMeaning
onTimeout (JS) / on_timeout (Python)"kill"Default behavior. The sandbox is removed after its timeout.
onTimeout (JS) / on_timeout (Python)"pause"The sandbox is paused after the timeout instead of being deleted.
autoResume (JS) / auto_resume (Python)falseDefault behavior. Paused sandboxes stay paused until resumed manually.
autoResume (JS) / auto_resume (Python)truePaused sandboxes restart when supported activity arrives. This requires timeout behavior to be "pause".
If auto-resume is disabled or omitted, a paused sandbox can still be resumed manually with Sandbox.connect().

​
Auto-pause

By default, a sandbox is killed when its timeout expires. To keep the state instead, set the on_timeout option in lifecycle behavior to pause on timeout. 
import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create({
  timeoutMs: 300_000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: false,
  },
})

await sandbox.kill()

​
Auto-resume

Auto-resume can wake a paused sandbox when supported activity arrives. This works only when the sandbox is configured to pause on timeout.

​
Timeout after auto-resume

After an automatic resume, the sandbox receives a timeout of at least five minutes. If the original timeout was longer than five minutes, the longer original value is reused. The timeout timer starts when the sandbox resumes, not when it was originally created. Example with a two-minute timeout:
  1. The sandbox runs for two minutes and then pauses.
  2. New activity reaches the sandbox, causing it to resume.
  3. The resumed sandbox receives a five-minute timeout because that is the minimum.
  4. If nothing resets the timer, the sandbox pauses again after five minutes.
Example with a one-hour timeout:
  • The sandbox resumes with a one-hour timeout, because the original timeout is longer than the five-minute minimum.
This behavior continues across future pause and resume cycles, because the lifecycle settings remain attached to the sandbox.
You can update the timeout after resuming by using setTimeout() in JavaScript or set_timeout() in Python.

​
What counts as activity

Auto-resume can be triggered by SDK actions and HTTP traffic. Supported examples include:
  • sandbox.commands.run(...)
  • sandbox.files.read(...)
  • sandbox.files.write(...)
  • Visiting a tunneled application URL
  • Sending requests to a service running inside the sandbox
When a sandbox is paused and auto-resume is enabled, the next supported action resumes it automatically. You do not need to call Sandbox.connect() first.

​
SDK example: pause, then read a file

This example creates a sandbox, writes a file, pauses the sandbox, and then reads the file. The read operation causes the sandbox to resume. 
import { Sandbox } from 'novita-sandbox'

const sandbox = await 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}`)

​
Example: Web server with auto-resume

Auto-resume works well for preview environments and web servers. After the sandbox pauses, an incoming HTTP request to the exposed service can wake it. The example below starts a simple Python HTTP server and prints a public preview URL. You can use getHost() in JavaScript or get_host() in Python to retrieve the public hostname for a port. 
import { Sandbox } from 'novita-sandbox'

const sandbox = await 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)
// Once the sandbox times out and pauses, any request to the preview URL will automatically resume it.
console.log(`Preview URL: https://${host}`)

​
Cleanup

Auto-resume remains enabled across repeated resume and pause cycles. Every resume starts a new timeout period, using at least five minutes or the longer original timeout. After the sandbox resumes, clients should reconnect to any services they were using. Existing HTTP, WebSocket, database, and terminal connections do not stay open while the sandbox is paused. You can call .kill() to delete the sandbox permanently. After that, it cannot be resumed.
Last modified on June 10, 2026