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 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.

import { Sandbox } from "@superserve/sdk"

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

await sandbox.pause()

from superserve import Sandbox

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

sandbox.pause()

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