feat(api): add sandbox fork endpoint

[mishushakov]

Summary

• Adds POST /sandboxes/{sandboxID}/fork: checkpoints the running sandbox in place and creates one or more new sandboxes from that snapshot under fresh IDs.
• The checkpoint reuses the mechanism behind snapshot templates (Sandbox.Checkpoint gRPC): the sandbox is briefly paused on its node, snapshotted to its own snapshots row, and resumed under the same execution ID — the original never leaves the sandbox store, so its ID, expiration, node placement, and concurrency reservation are untouched.
• SandboxForkRequest supports an optional timeout (TTL for the forked sandboxes, defaults to the standard 15s sandbox default) and count (number of forks, default 1). The snapshot is captured once regardless of count; all forks boot from it in parallel.
• Per-fork results: the 201 response is a list of SandboxForkResult, each holding either the created sandbox or the error that prevented it from starting (Promise.allSettled-style). A non-201 status means the request failed before any fork was attempted. Checkpoint always captures full memory state; forking requires a snapshot-capable envd (400 otherwise).
• Splits the resume data fetcher into buildResumeSandboxData (resume from own snapshot) and buildResumeSandboxDataFromSnapshot (boot a different ID from a snapshot), so each forked sandbox's envd access token is generated for the ID it actually runs under.
• Threads SnapshotSandboxID through SandboxMetadata so the resume origin-node remap on placement timeout targets the snapshot's row (previously a silent no-op when the started ID differed from the snapshot's).
• Regenerated packages/api/internal/api/api.gen.go and the integration test client from the updated OpenAPI spec.

Test plan

• go build/go vet/go test -race pass for packages/api/... and tests/integration
• make fmt and scoped golangci-lint run on touched packages are clean
• Integration tests: happy-path fork (original and fork both running afterwards), multi-fork with count: 2 (unique IDs, all running, no per-fork errors), invalid count: 0 (400), forking a paused sandbox (409), forking a killed sandbox (404), cross-team access (404)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[cursor]

PR Summary

Medium Risk
New sandbox lifecycle path reuses snapshot/checkpoint gRPC and can kill the source on checkpoint failure; parallel forks up to 100 interact with team concurrency and placement limits.

Overview
This PR exposes forking a running sandbox via POST /sandboxes/{sandboxID}/fork. The handler checkpoints the source in place (pause, full-memory snapshot to that sandbox’s snapshot row, resume under the same ID so TTL and concurrency stay unchanged), then starts up to count new sandboxes in parallel from that snapshot, each with its own ID and optional TTL. The 201 body is a per-fork result list (sandbox or error), while 4xx/5xx mean nothing was forked. Resume-from-snapshot wiring now separates which ID owns the snapshot from which ID is being started, including envd tokens and origin-node remap on placement timeout. OpenAPI and generated API clients are updated accordingly, with integration coverage for the new flow.

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

[codecov]

❌ 2 Tests Failed:

Tests completed	Failed	Passed	Skipped
3174	2	3172	6

View the top 3 failed test(s) by shortest run time

github.com/e2b-dev/infra/packages/api/internal/sandbox/storage/redis::TestStorageLocker_ObtainUsesProvidedContext

Stack Traces | 14.7s run time

=== RUN   TestStorageLocker_ObtainUsesProvidedContext
=== PAUSE TestStorageLocker_ObtainUsesProvidedContext
=== CONT  TestStorageLocker_ObtainUsesProvidedContext
    lock_test.go:97: 
        	Error Trace:	.../storage/redis/lock_test.go:289
        	            				.../storage/redis/lock_test.go:97
        	Error:      	Received unexpected error:
        	            	context deadline exceeded
        	Test:       	TestStorageLocker_ObtainUsesProvidedContext
--- FAIL: TestStorageLocker_ObtainUsesProvidedContext (14.67s)

github.com/e2b-dev/infra/tests/integration/internal/tests/orchestrator::TestHardwareEntropyDeviceAvailability

Stack Traces | 18.7s run time

=== RUN   TestHardwareEntropyDeviceAvailability
=== PAUSE TestHardwareEntropyDeviceAvailability
=== CONT  TestHardwareEntropyDeviceAvailability
    sandbox_entropy_test.go:25: Command [bash] output: event:{start:{pid:1138}}
    sandbox_entropy_test.go:26: 
        	Error Trace:	.../tests/orchestrator/sandbox_entropy_test.go:26
        	Error:      	Received unexpected error:
        	            	failed to execute command bash in sandbox i7jsrxuab569adoz83c9s: invalid_argument: protocol error: incomplete envelope: unexpected EOF
        	Test:       	TestHardwareEntropyDeviceAvailability
--- FAIL: TestHardwareEntropyDeviceAvailability (18.74s)

github.com/e2b-dev/infra/tests/integration/internal/tests/api/sandboxes::TestSandboxConnect_FilesystemOnlyResumes

Stack Traces | 61.5s run time

=== RUN   TestSandboxConnect_FilesystemOnlyResumes
=== PAUSE TestSandboxConnect_FilesystemOnlyResumes
=== CONT  TestSandboxConnect_FilesystemOnlyResumes
Executing command cat in sandbox i19uvq6mn0d1opxd9z486 (user: root)
    filesystem_only_test.go:92: 
        	Error Trace:	.../api/sandboxes/filesystem_only_test.go:92
        	Error:      	Not equal: 
        	            	expected: 201
        	            	actual  : 500
        	Test:       	TestSandboxConnect_FilesystemOnlyResumes
        	Messages:   	connecting to a paused filesystem-only snapshot should resume it (cold boot)
--- FAIL: TestSandboxConnect_FilesystemOnlyResumes (61.46s)

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[gemini-code-assist]

Code Review

In packages/api/internal/handlers/sandbox_fork.go, the parsed request body returned by ParseOptionalBody can be nil if the request body is omitted. Accessing body.Timeout and body.Memory without a nil check will cause a runtime panic, so a nil check must be added before dereferencing these fields.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bf16ec1. Configure here.}