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. connect() and resume() wait a pause out for you; a pause still finishing after that wait answers 409 with code sandbox_pausing and a Retry-After header, so 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. A waited pause is a single request the server holds until the pause lands, so it costs no polling.

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

Idle timeout

Set idleTimeoutSeconds to auto-pause a sandbox after this many seconds with no activity. Unlike timeoutSeconds, the idle timeout never pauses a sandbox while a request or connection to it is open. Use it for a sandbox that must stay active while someone works in it and stop billing when it goes quiet.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "dev-box",
  idleTimeoutSeconds: 600, // auto-pause after 10m with no activity
})

from superserve import Sandbox

sandbox = Sandbox.create(
    name="dev-box",
    idle_timeout_seconds=600,  # auto-pause after 10m with no activity
)

superserve sandbox create --name dev-box --idle-timeout 10m  # 1m to 7d

Requires SDK 0.11.6+ (@superserve/sdk and superserve), CLI 2.1.2+, and MCP 0.3.4+ (@superserve/mcp). Older TypeScript SDK versions ignore idleTimeoutSeconds and show no error.

These count as activity and keep the sandbox active:

A running command, including a commands.run() call that streams output for a long time.
An open terminal or command stream, even when nothing is typed.
File reads, writes, and directory listings, and saved-snapshot captures.
Desktop actions, such as screenshots, clicks, and typing.
Traffic to the sandbox’s preview URLs.

These don’t count as activity:

Outbound traffic from the sandbox, such as downloads or calls to other APIs.
A background process started with nohup or &. After the command that started it returns, the process does not keep the sandbox active.
CPU or disk activity on its own.
Changes to the sandbox’s settings, such as metadata or egress rules.

Background jobs and outbound-only workloads, such as an agent loop that only calls external APIs, do not keep the sandbox active. The idle timeout can pause the sandbox while this work runs. For this kind of work, use timeoutSeconds or leave the idle timeout unset.

The sandbox pauses shortly after the idle timeout expires. As with any pause, Superserve checkpoints the memory and filesystem, and the next commands.run(), file operation, or connect() resumes the sandbox where it stopped. Each resume restarts the idle count. The value can be 60 to 604800 seconds (7 days). By default, the idle timeout is unset, and the sandbox never pauses for being idle.

A raw HTTP request that uses X-Access-Token does not resume a paused sandbox. It fails with a 503 error (sandbox_unavailable). Call POST /sandboxes/{sandbox_id}/activate first, then send the request with the returned access token.

idleTimeoutSeconds and timeoutSeconds are independent. Whichever expires first pauses the sandbox. Use both to pause an inactive sandbox and also cap a session that never goes quiet. Set, clear, or read the idle timeout on an existing sandbox. When the idle timeout is off, the current value is undefined (TypeScript) or None (Python):

await sandbox.update({ idleTimeoutSeconds: 900 }) // auto-pause after 15m with no activity
await sandbox.update({ idleTimeoutSeconds: null }) // turn idle pausing off
const { idleTimeoutSeconds } = await sandbox.getInfo() // current value

sandbox.update(idle_timeout_seconds=900)  # auto-pause after 15m with no activity
sandbox.update(idle_timeout_seconds=None)  # turn idle pausing off
idle_timeout = sandbox.get_info().idle_timeout_seconds  # current value

superserve sandbox update dev-box --idle-timeout 15m   # auto-pause after 15m with no activity
superserve sandbox update dev-box --idle-timeout none  # turn idle pausing off
superserve sandbox get dev-box                         # shows "Idle timeout: 15m" or "none"

A new value takes effect immediately. If the new value is shorter than the time the sandbox has already been idle, the sandbox pauses shortly after the change.

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 or idleTimeoutSeconds: 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

Idle timeout

Auto-delete

​Pause

​Resume

​Kill

​Kill without an instance

​Auto-pause

​Idle timeout

​Auto-delete

Pause

Resume

Kill

Kill without an instance

Auto-pause

Idle timeout

Auto-delete