Skip to content

feat(sandboxes): volume sync command and SDK method - #1163

Open
akirillo wants to merge 5 commits into
mainfrom
feature/sandbox-volumes-sync
Open

akirillo wants to merge 5 commits into
mainfrom
feature/sandbox-volumes-sync

Conversation

@akirillo

@akirillo akirillo commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Adds prime sandbox volumes sync <name> --sandbox <id> [--discard] [--no-wait] and the SDK Volumes.sync / AsyncVolumes.sync, driving the new platform endpoint POST/GET /api/v1/sandbox/{id}/volumes/{name}/sync (platform PR-A https://github.com/PrimeIntellect-ai/platform/pull/7459; design https://github.com/PrimeIntellect-ai/platform/pull/7436).

  • sync brings a volume mounted in a RUNNING sandbox to the volume's committed head. RW attachments publish first (platform PR-B), --discard drops unpublished local writes.
  • Waits by default (720 s: the 600 s server deadline plus its ~1 min enforcement tick), polling with the checkpoint waiter's shared pacing (fixed fast cadence for the first seconds, then jittered exponential backoff; helpers moved to _polling); prints the synced head checkpoint on DONE. --plain as for publish.
  • Response contract (final server schema): {sync_id, state, head_id, updated_at, failure}; states UNMOUNTING | PUBLISHING | REMOUNTING | DONE | FAILED; failure (nullable: BUSY | PUBLISH_FAILED | MERGE_FAILED | DEADLINE | NODE_ERROR | ROLLBACK_FAILED, platform PR #8119) is set on FAILED. FAILED exits 1 with volume sync failed: <failure> (BUSY adds the hint "a process in the sandbox holds the volume; close it and retry"), for both wait and --no-wait; VolumeSyncFailedError.failure carries the code; wait expiry hints to re-run (a repeated request returns the same in-flight sync). --no-wait reports a terminal state carried by the POST response itself: DONE prints the completed sync, FAILED exits 1.
  • SDK: VolumeSync model mirrors the ingress schema; VolumeSyncFailedError on FAILED; TimeoutError on expiry. sandbox_id is the first parameter like publish; timeout_seconds follows SDK naming.

Rebased onto main after #1099 (force removal, merge-aware publish wait, fast-then-backoff checkpoint polling); the sync wait reuses that shared poll pacing instead of its own backoff.

  • The checkpoint and sync waits cap their backoff at 2 s (CHECKPOINT_POLL_MAX_DELAY), so a sync finishing after the 10 s fast window is seen within ~2 s, not ~10 s; sandbox creation keeps its 10 s cap.

Release after the platform PR-A deploys.

  • The wait is pinned to the sync_id the POST returned; if another request replaced it, VolumeSyncSupersededError (CLI: exit 1, "run again") instead of reporting someone else's result. A re-run still POSTs: the server joins an in-flight sync and 409s on a --discard mismatch, which a GET-first would bypass.
  • VolumeSync docs now list ROLLING_BACK (failure already set while the volume is re-attached at its previous head).
  • sandbox create --volume NAME:/path:rw parses :rw (previously mounted at the literal path /path:rw); unknown suffixes are rejected.
  • volumes create --from: rsync shows --info=progress2 (falls back to --progress on openrsync, which lacks it) and ssh runs with LogLevel=ERROR, so the 'Permanently added' warning is gone. Host-key pinning is not possible here: sandbox SSH sessions return no host key (unlike the volume sessions volumes.py pins); it needs an API change. Ownership is documented in --from help, not mapped.
  • sync --discard prints 'Discarded unpublished changes'; ROLLBACK_FAILED hints --discard. fork help says volumes are remounted at their published heads (platform #8228).

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-05T21:11:57.632478Z c8c0363 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8c0363021

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@akirillo
akirillo force-pushed the feature/sandbox-volumes-sync branch 3 times, most recently from 56b4c69 to 206ce72 Compare November 19, 2026 01:15
SDK: Volumes.sync / AsyncVolumes.sync request a sync of one attached
volume of a running sandbox (POST /sandbox/{id}/volumes/{name}/sync,
body {discard}) and, with wait=True (the default), poll the sync GET
until DONE or FAILED within timeout_seconds (default 600s, the server's
own sync deadline). The wait shares the checkpoint waiter's poll pacing
(fixed fast cadence for the first seconds, then jittered exponential
backoff); the shared helpers moved to the new _polling module so both
waits use one law. FAILED raises the new VolumeSyncFailedError (a
RuntimeError) pointing at the sandbox's volume sync logs - the response
carries no error detail; expiry raises TimeoutError. The VolumeSync
model mirrors the ingress VolumeSyncResponse: sync_id, state
(UNMOUNTING | PUBLISHING | REMOUNTING | DONE | FAILED), head_id,
updated_at.

CLI: `prime sandbox volumes sync <name> --sandbox <id> [--discard]
[--no-wait]` waits by default and prints the synced head checkpoint on
DONE; FAILED exits 1 with "volume sync failed (state FAILED); see the
sandbox's volume sync logs" and a wait timeout hints to re-run (a
repeated request returns the same in-flight sync). --no-wait reports a
terminal state carried by the POST response itself: DONE prints the
completed sync, FAILED exits 1.
A wait finishing after the 10 s fast window was seen up to ~10 s late. Checkpoint and sync waits now back off to 2 s; sandbox creation keeps its 10 s cap.
Default the sync wait to 720 s so a server-side DEADLINE or ROLLBACK_FAILED
arrives before the client gives up, pin the waiter to the sync it started
(VolumeSyncSupersededError when another sync replaced it), and document the
ROLLING_BACK state.
@akirillo
akirillo force-pushed the feature/sandbox-volumes-sync branch from 063ffe9 to 9754aa9 Compare November 19, 2026 08:27

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant