Archive a sandbox to its filesystem, and unarchive it back

[devin-ai-integration]

Summary

The control plane can now archive a sandbox — export the filesystem changes it made over its image, then release its compute — and unarchive it later. This exposes both as sandbox methods, in the async and the sync SDK, on the instance and on the class:

await sandbox.archive()                       # returns once ARCHIVED
await sandbox.unarchive()                     # returns once DEPLOYED again
await sandbox.archive(wait=False)             # returns as soon as the export is launched
await SandboxInstance.unarchive("my-sandbox") # like delete/fork, by name

Both the export and the restore run in the background (minutes for a few gigabytes), so wait=True is the default and polls the sandbox record: archive until ARCHIVED, unarchive until DEPLOYED, both with a configurable timeout (30 min) and interval (2 s). A sandbox that leaves the states the operation goes through — say a failed export gives it back as DEPLOYED/FAILED — raises instead of waiting out the timeout.

Both forms share one descriptor, so the class-level and the instance form cannot drift:

SandboxInstance.archive = _AsyncSandboxCallDescriptor(
    _archive_sandbox_by_name, "archive", target="ARCHIVED", pending={"DEPLOYED", "ARCHIVING"}, ...
)

The instance form writes the refreshed record back into the shared SandboxConfiguration, so sandbox.fs/sandbox.process and a forced session URL keep working across the call.

Generated client: archive_sandbox/unarchive_sandbox, the SandboxArchive/SandboxArchiveRestore models, and the ARCHIVING/ARCHIVED/UNARCHIVING statuses.

The integration test is gated behind RUN_SLOW_TESTS: an archive and its restore take minutes each way, well past the one-minute budget.

Link to Devin session: https://app.devin.ai/sessions/43a2b5615507438a8abb55723c9298e3
Requested by: @drappier-charles

---

Note

Medium Risk
Introduces long-running lifecycle operations with status polling; incorrect wait logic could mislead callers about when the filesystem is safe to write, though changes follow existing sandbox API patterns and are well covered by unit tests.

Overview
Adds sandbox archive/unarchive to the Python SDK so callers can export writable filesystem state to the archive store (releasing compute) and later restore it onto a new instance with processes restarted from saved configuration—not live memory.

Generated client: new POST /sandboxes/{name}/archive and unarchive helpers (sync/async), Sandbox.archive metadata models (SandboxArchive, restore progress), and deployment statuses ARCHIVING, ARCHIVED, and UNARCHIVING.

High-level API: SandboxInstance and SyncSandboxInstance expose archive() and unarchive() on both the class (by name, like delete) and the instance. By default they poll until ARCHIVED or DEPLOYED (30 min timeout, 2 s interval), with wait=False to return immediately; failed or unexpected status transitions raise SandboxAPIError instead of hanging. Instance calls refresh the embedded sandbox record so fs/process keep working.

Tests: mocked coverage for wait/timeout/failure paths plus opt-in slow integration tests (RUN_SLOW_TESTS) for filesystem retention and preview URL stability across archive/restore.

^{Reviewed by Cursor Bugbot for commit 8218851. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 2 potential issues.