Pause, resume, and delete

A sandbox transitions between two long-lived states:

active - VM is running, processes executing, compute billed
paused - VM paused, state persisted to disk, no compute billed

You’ll briefly see pausing while a sandbox is being checkpointed and resuming while a paused sandbox is being restored to active - retry shortly. failed indicates the sandbox couldn’t boot or resume; the entry remains until you delete it. Deletion removes the sandbox entirely; further API calls return 404.

active  ↔  paused  →  deleted

Pause

pause() checkpoints the full VM state (memory, processes, filesystem) to disk and stops billing for compute. It returns once the pause is accepted and the sandbox finishes pausing on its own; pass wait: true / wait=True to return once the sandbox is paused.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "long-job" })

await sandbox.pause()
// or, to return only once the sandbox is paused:
// await sandbox.pause({ wait: true })

from superserve import Sandbox

sandbox = Sandbox.create(name="long-job")

sandbox.pause()
# or, to return only once the sandbox is paused:
# sandbox.pause(wait=True)

Resume

resume() restores a paused sandbox you already hold a reference to. Processes pick up where they left off.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "long-job" })
await sandbox.pause()
await sandbox.resume()
await sandbox.commands.run("ls /tmp")

from superserve import Sandbox

sandbox = Sandbox.create(name="long-job")
sandbox.pause()
sandbox.resume()
sandbox.commands.run("ls /tmp")

A paused sandbox is auto-resumed by both Sandbox.connect() and commands.run().

After a resume, keep using the same sandbox — your commands and files calls keep working with no changes on your side.

Kill

kill() deletes the sandbox and all its resources. It’s idempotent - deleting an already-deleted sandbox is a no-op that swallows the 404.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "one-shot" })

await sandbox.kill()

from superserve import Sandbox

sandbox = Sandbox.create(name="one-shot")

sandbox.kill()

Kill without an instance

In serverless contexts you often don’t have the sandbox - just the ID. Use killById / kill_by_id to delete it anyway.

import { Sandbox } from "@superserve/sdk"

await Sandbox.killById("7a3f2b8c-1234-...")

from superserve import Sandbox

Sandbox.kill_by_id("7a3f2b8c-1234-...")

Auto-pause

Set timeoutSeconds to auto-pause a sandbox after it has been active for that long. Pausing checkpoints its state and stops compute billing, so a sandbox you forget about won’t keep running and billing. It isn’t deleted; the next commands.run(), file operation, or connect() resumes it where it left off.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "worker",
  timeoutSeconds: 3600, // auto-pause after 1h of active time
})

from superserve import Sandbox

sandbox = Sandbox.create(
    name="worker",
    timeout_seconds=3600,  # auto-pause after 1h of active time
)

The timeout is scoped to the current active session:

It’s a cap on active time, not idle time. Running work doesn’t reset it, so a task still going when the window elapses is paused mid-run. Size it for your longest active session.
Each resume starts a fresh window.
The sandbox is paused, not deleted. Resume restores full memory and filesystem.
Leave it unset (the default) to disable auto-pause; the sandbox stays active until you pause or kill it.

Set or clear it on an existing sandbox:

await sandbox.update({ timeoutSeconds: 900 }) // auto-pause after 15m active
await sandbox.update({ timeoutSeconds: null }) // disable auto-pause

sandbox.update(timeout_seconds=900)  # auto-pause after 15m active
sandbox.update(timeout_seconds=None)  # disable auto-pause

Auto-delete

By default a paused sandbox is kept forever. Set autoDeleteSeconds to delete it once it has been continuously paused for that long. This suits short-lived or unattended sandboxes: scheduled jobs, one-off experiments, or agent sessions that never get an explicit kill().

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "scratch-job",
  autoDeleteSeconds: 3600, // delete after 1h of continuous pause
})

from superserve import Sandbox

sandbox = Sandbox.create(
    name="scratch-job",
    auto_delete_seconds=3600,  # delete after 1h of continuous pause
)

The countdown is tied to the paused state:

Pause starts it and resume cancels it. Pausing again starts a fresh window, so a sandbox in use is never deleted.
0 deletes the sandbox as soon as it pauses.
While paused, the sandbox’s info includes autoDeleteAt, the exact deletion time.
Maximum window: 30 days.

You can also set or clear the window on an existing sandbox:

// Arm: delete after 1h of continuous pause. On an already-paused sandbox
// the countdown starts now, so you always get the full window.
await sandbox.update({ autoDeleteSeconds: 3600 })

// Disarm: keep the sandbox until explicitly killed.
await sandbox.update({ autoDeleteSeconds: null })

# Arm: delete after 1h of continuous pause. On an already-paused sandbox
# the countdown starts now, so you always get the full window.
sandbox.update(auto_delete_seconds=3600)

# Disarm: keep the sandbox until explicitly killed.
sandbox.update(auto_delete_seconds=None)

Pair autoDeleteSeconds with timeoutSeconds: the timeout pauses the sandbox, then the auto-delete window cleans it up. A sandbox that never pauses is never auto-deleted.

Get Started

Sandbox

Secrets & env vars

Templates

Commands

Filesystem

Storage

Errors

Pause, resume, and delete

Pause

Resume

Kill

Kill without an instance

Auto-pause

Auto-delete

​Pause

​Resume

​Kill

​Kill without an instance

​Auto-pause

​Auto-delete

Pause

Resume

Kill

Kill without an instance

Auto-pause

Auto-delete