Skip to main content
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. 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.
For automatic pause on timeout and auto-resume on activity, see Auto Pause and Resume. For idle timeout, see Idle timeout.
Please note:
  • It takes about 4 seconds per 1 GB RAM to pause the sandbox.
  • It takes about 1 second to resume the sandbox.
  • The data of a paused sandbox is retained until you explicitly call the kill method.

​
Pause a sandbox

You can call pause method when you want to save the current state. 
import { Sandbox } from 'novita-sandbox/code-interpreter'

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

const sandboxId = sandbox.sandboxId
await sandbox.pause()

console.log('Sandbox paused', sandboxId)

​
Resume a sandbox

Use the saved sandbox ID to connect again. If the sandbox is paused, you can use connect method to resumes it before returning. 
import { Sandbox } from 'novita-sandbox/code-interpreter'

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

await sandbox.kill()
You can pass a new timeout when reconnecting. 
import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.connect(sandboxId, { timeoutMs: 600_000 })

await sandbox.kill()
For a running sandbox, the timeout is updated only when the new timeout is longer than the existing one. For a paused sandbox, the timeout applies after it resumes.

​
List paused sandboxes

You can use the list method with a state filter to find paused sandboxes. More information about using the method can be found in List Sandboxes. 
import { Sandbox } from 'novita-sandbox/code-interpreter'

const paginator = Sandbox.list({
  query: {
    state: ['paused'],
  },
})

while (paginator.hasNext) {
  const items = await paginator.nextItems()
  for (const info of items) {
    console.log(info.sandboxId, info.state, info.metadata)
  }
}
Metadata filters are useful when you need to find sandboxes created by a specific user, session, or job.

​
Delete a paused sandbox

Paused sandboxes remain stored until you remove them. You can use the kill method to remove paused sandboxes that you no longer need. 
import { Sandbox } from 'novita-sandbox/code-interpreter'

await Sandbox.kill(sandboxId)

​
Persistence vs snapshots

Persistence is for continuing the same sandbox later. Use it when you care about the exact sandbox ID and current running state. Snapshots are for creating reusable saved states. Use a snapshot when you want to start one or more new sandboxes from the same captured filesystem and memory state. For reusable states, see Sandbox Snapshot.

​
Network

If you pause a sandbox that has a running service, the service becomes inaccessible from outside the sandbox and any connected clients are disconnected. After you resume the sandbox, the service becomes accessible again, but clients must reconnect.
Last modified on June 8, 2026