Support idempotent sandbox creation with a client-supplied request identity

[talgat0528]

Is your feature request related to a problem? Please describe.

Durable orchestrators cannot safely recover an ambiguous sandbox-creation result through the current Python SDK/API contract. AsyncSandbox.create() accepts metadata, but no client-supplied idempotency identity. If the provider accepts POST /sandboxes and the client process dies or loses the response, a retry can create a second sandbox. Avoiding the retry can instead strand work when the original request never committed.

Listing by metadata does not close this gap: metadata is not a uniqueness constraint, and an empty observation cannot prove that an in-flight create will not become visible later.

Describe the solution you'd like

Support a client-supplied idempotency key for sandbox creation in the API and Python SDK, with a documented contract such as:

• concurrent or later retries with the same key and equivalent create parameters return the exact same sandbox identity;
• reuse of the key with different create parameters returns a typed conflict;
• acknowledgement loss and request timeouts do not permit duplicate allocations;
• the retention period and terminal retry behavior are documented;
• the idempotency key is treated as request identity rather than guest-visible metadata.

This would let a caller durably persist an allocation intent before dispatch and then safely replay creation after process loss.

Describe alternatives you've considered

• Querying by unique-looking metadata and adopting one result is observational, not atomic, and can miss a late allocation.
• Creating again and deleting duplicates still has an unbounded late-arrival window.
• Never retrying fails closed but leaves an allocation intent permanently unresolved when the first request did not commit.

Additional context

This requirement was found while implementing crash-recoverable remote environment allocation in Cayu: https://github.com/vertexkg/cayu/issues/540

The audited SDK version is e2b==2.28.0.

[jinngimk-lang]

This is a great real-world breaker because it sits right on the line between “request sent” and “resource definitely exists exactly once.” Durable agents cannot safely infer that from an empty list or a timeout.

AgentCI is collecting crash/retry cases like this and turning them into executable evidence contracts. A strong fixture here is: persist intent → lose the create acknowledgement → retry with the same identity → prove exactly one sandbox identity and a typed conflict on parameter drift. If you or an external agent contribute the minimal reproducible case, we’ll preserve the upstream provenance and credit the reproducer in the public Breaker Hall of Fame when it is accepted into the corpus.

AgentCI: https://github.com/jinngimk-lang/agentci
Credit/challenge rules: https://github.com/jinngimk-lang/agentci/blob/main/COMMUNITY.md

No E2B security/certification claim — we’re interested in the portable “ambiguous effect + retry” contract.

[devin-ai-integration]

Triage

• type: feature
• priority: medium
• complexity: large
• affected_area: API (infra) + python-sdk / sandbox creation
• actionable: partially — requires an API-side idempotency contract decision before SDK work can start
• needs_clarification: false
• summary: Request for a client-supplied idempotency key on sandbox creation so durable orchestrators can safely retry ambiguous create results without duplicating sandboxes; needs infra/API support plus SDK plumbing.

Written by Devin