Pause

Pause a running sandbox to freeze its execution.

sandbox.pause() -> Dict[str, Any]

Paused VMs still consume memory and count toward your concurrent sandbox limit.

Returns

sandbox_idstr

The ID of the paused sandbox.

pausedbool

Always True after successful pause operation.

paused_atstr

ISO 8601 timestamp when the sandbox was paused.

Examples

Basic Pause

from concave import Sandbox

sbx = Sandbox.create()

# Create a file to demonstrate state preservation
sbx.execute("echo '42' > /tmp/value.txt")

# Pause the sandbox
result = sbx.pause()
print(f"Paused: {result['paused']}")
print(f"Paused at: {result['paused_at']}")

# Resume later
sbx.resume()

# File system state is preserved
output = sbx.execute("cat /tmp/value.txt")
print(output.stdout)  # "42"

sbx.delete()

Pause During Long Operation

from concave import Sandbox
import time

sbx = Sandbox.create()

# Create setup files
sbx.execute("mkdir -p /tmp/workspace")
sbx.execute("echo 'setup complete' > /tmp/workspace/status.txt")

# Pause to save resources while waiting
sbx.pause()
print("Sandbox paused, saving resources...")

# Do other work...
time.sleep(60)

# Resume when ready
sbx.resume()
print("Sandbox resumed, continuing work...")

# Files are still there
status = sbx.execute("cat /tmp/workspace/status.txt")
print(status.stdout)  # "setup complete"

sbx.delete()

With Error Handling

from concave import Sandbox, SandboxClientError

sbx = Sandbox.create()

try:
    sbx.pause()
    print("Sandbox paused successfully")
    
    # Try to pause again (will raise error)
    sbx.pause()
except SandboxClientError as e:
    if "already paused" in str(e):
        print("Sandbox is already paused")
finally:
    sbx.delete()

Exceptions

SandboxClientErrorException

Raised when the sandbox is already paused (HTTP 409 Conflict).

SandboxNotFoundErrorException

Raised when the sandbox no longer exists or has been deleted.

SandboxUnavailableErrorException

Raised when the sandbox service is unavailable or the VM cannot be paused.

SandboxTimeoutErrorException

Raised when the pause request times out.