Suspend and resume stateful agent sandbox jobs with SPACE
Run a stateful job in self-hosted SPACE, preserve sandbox state across suspension, and reconcile operation IDs, readiness and command transcripts before continuing.
npx skills add agentskillexchange/skills --skill suspend-and-resume-stateful-agent-sandbox-jobs-with-space
Use this workflow when a self-hosted agent job must preserve a SPACE Firecracker sandbox across a pause or suspension and resume work with explicit readiness and recovery checks. The operator supplies a configured SPACE endpoint, permitted template, bounded command and a policy for keeping or deleting the environment. Keep sandbox IDs, operation IDs, mutation request bodies, idempotency keys and output transcripts in a private run record without bearer tokens.
What this skill actually does
Invoke it for a stateful agent task that needs a controlled stop and continuation, or when a timeout leaves the outcome of an asynchronous sandbox request uncertain. The output is an inspected sandbox state and verified command result with recovery evidence, rather than another disposable execute-and-delete code runner.
The boundary is one authorized sandbox job through the native HTTP API: create and wait, attach a command, capture its terminal result, pause or suspend, wake and recheck readiness, then explicitly retain or delete the sandbox. It excludes general cluster administration, production deployment hardening and assumptions of compatibility with every E2B client.
Begin with the documented examples/first_sandbox.py walkthrough. From the prepared repository and authenticated shell run python3 examples/first_sandbox.py. Save the private run directory it prints. A command starts when its session is attached; decode the streamed output and require process_exited with the expected exit code. A successful HTTP response or a closed stream does not establish successful execution.
For state preservation, the documented native endpoints are POST /v1/sandboxes/{id}:pause, :suspend and :wake. Pause keeps the VM resident; suspend saves VM state and filesystem while releasing active VM resources. Use the exact request contract in the deployment’s /openapi-m1.json, an Idempotency-Key per lifecycle mutation and the returned operation ID. Poll the operation, and after wake verify running state and process readiness before sending new commands.
If a result is uncertain, use python3 examples/first_sandbox.py inspect <run-directory> and reconcile the saved request and returned IDs before retrying. The documented stream does not replay missed output through Last-Event-ID; resync_required is a failure requiring inspection, not a reason to rerun side effects blindly. Preserve transcripts for diagnosis. Use the documented delete command only after operator confirmation, and require the deletion operation to succeed.
Installation: Clone https://github.com/perplexityai/SPACE.git and review docs/installation.md at the chosen revision. The documented local setup requires apt-based Linux x86_64 with KVM, privileged local Docker, tun/loop devices and btrfs support. Follow the documented prerequisite, Firecracker vendor and Kind bootstrap steps; wait for template publication and node readiness. Configure SPACE_API_URL, SPACE_DATA_PLANE_URL and SPACE_API_TOKEN as documented without recording tokens in run artifacts. From the configured checkout run python3 examples/first_sandbox.py. This is a private local setup with development defaults; it is not a production deployment recipe.
Framework fit: Multi-Framework because the upstream native HTTP and event-stream interface does not depend on an agent runtime or model. SPACE is pre-1.0: the inspected versioning guide describes a 0.8 public baseline, permits minor-version breaking changes and reserves stable lifecycle guarantees for 1.0. Pin and review the deployed revision; this entry does not claim stable production compatibility or a security audit. Metadata and documented invocation were verified; deployment and runtime behavior were not tested.