sandbox: dynamic directory mount & snapshot in go + adds detach #246

thomasjpfan · 2026-01-26T22:47:34Z

This PR cherry picks files from the following PRs to just implement the dynamic directory mounts for Go:

This includes the task command router. I think this is a smaller change and does not impact any public API around sb.exec. Once we have this in, then #242 is easier to review.

cursor · 2026-01-26T22:47:40Z

PR Summary

Medium Risk
Introduces a new gRPC client path (task command router) with JWT refresh/retry logic and changes the Sandbox.Terminate API, so regressions could affect sandbox lifecycle and new mount/snapshot behavior.

Overview
Adds sandbox connection lifecycle management to Go: Sandbox.Detach() closes command-router resources and makes the Sandbox object unusable thereafter (SandboxDetached), while Sandbox.Terminate now takes a detach flag (plus params) to optionally detach after terminating.

Introduces experimental dynamic directory mount & snapshot for Sandboxes via a new TaskCommandRouterClient (JWT-based auth with refresh + transient retry), exposed as Sandbox.ExperimentalMountImage and Sandbox.ExperimentalSnapshotDirectory, and updates examples/tests/docs accordingly (including new mount/snapshot example and updated termination calls).

^{Written by Cursor Bugbot for commit 4c46034. This will update automatically on new commits. Configure here.}

modal-go/sandbox.go

ehdr · 2026-01-27T07:56:33Z

modal-go/task_command_router_client.go

+	"google.golang.org/protobuf/types/known/emptypb"
+)
+
+// tlsCredsNoALPN is a TLS credential that skips ALPN enforcement, implementing


I think this whole thing should no longer be needing after @saltzm fixed something server side, so might work if you just remove it and use the default?

modal-go/task_command_router_client.go

modal-go/sandbox.go

thomasjpfan · 2026-01-27T17:51:01Z

Updated PR with:

Remove the ALPN workaround and verify that taking to the TCR still works
Adds Detach back to both typescript and go

modal-js/src/sandbox.ts

modal-go/config.go

modal-go/task_command_router_client.go

modal-go/examples/sandbox-image-mount/main.go

modal-go/errors.go

modal-go/task_command_router_client.go

modal-go/test/sandbox_test.go

modal-go/test/sandbox_mount_image_test.go

modal-go/sandbox.go

thomasjpfan · 2026-01-27T22:08:33Z

I updated PR:

Disable almost every operation after Detach and added test for this behavior* (Details below)
Removed the JS changes, the PR is already getting too big. I'll open a smaller PR to add Detach to JS.

While implementing this, I made some decisions that are debatable:

Terminate is still allowed after Detach. It feels a little weird to not be able to terminate the sandbox after detach.
- I'm open to changing this.
Terminate does not mark the sandbox as detached, so you can still call sb.Wait after calling Terminate. Terminate will still close the task command routers.
- An alternative is to allow Terminate , Wait and Poll for a detached sandbox and have Terminate mark the sandbox as detached.

modal-go/config.go

saltzm

Everything looks good mod the comment about task_command_router_insecure which isn't being used anymore in the python client

modal-go/examples/sandbox-filesystem-snapshot/main.go

modal-go/examples/sandbox-image-mount/main.go

modal-go/sandbox.go

saltzm · 2026-01-28T19:15:30Z

modal-go/sandbox.go

 func (sb *Sandbox) ensureAttached() error {
 	if sb.detached.Load() {
-		return SandboxDetached{Exception: "Do not call Detach or Terminate until you are done with your sandbox in this session"}
+		return SandboxDetached{Exception: "Do not call Detach until you are done with your sandbox in this session"}


I think I might find this error message confusing if I do like sb.Exec() and get this back - I'll be like "why is it telling me not to call Detach, I'm calling Exec".

I'd expect something more like "Unable to perform operation on a detached sandbox" or "Operations on sandbox after Detach are not allowed" or some such thing

cursor

Cursor Bugbot has reviewed your changes and found 4 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-01-29T01:40:39Z

modal-go/examples/sandbox-filesystem-snapshot/main.go

 	fmt.Printf("Started Sandbox: %s\n", sb.SandboxID)
 	defer func() {
-		if err := sb.Terminate(context.Background()); err != nil {
+		if err := sb.Terminate(context.Background(), true, nil); err != nil {


Deferred terminate fails after manual detach in examples

Medium Severity

Deferred Terminate calls fail because the target sandbox is already detached. This occurs when a sandbox is explicitly detached or terminated with detach=true before the deferred call executes, leading to a fatal log.

Additional Locations (1)

modal-go/examples/sandbox-volume-ephemeral/main.go#L45-L50

cursor · 2026-01-29T01:40:39Z

modal-go/task_command_router_client.go

+	codes.Canceled:         {},
+	codes.Internal:         {},
+	codes.Unknown:          {},
+}


Duplicated retryable gRPC status codes map

Low Severity

commandRouterRetryableCodes is identical to retryableGrpcStatusCodes defined in client.go (lines 285-291). Both maps contain the exact same five gRPC status codes: DeadlineExceeded, Unavailable, Canceled, Internal, and Unknown. The existing retryableGrpcStatusCodes variable could be reused instead of defining a duplicate.

cursor · 2026-01-29T01:40:39Z

modal-go/task_command_router_client.go

+type RetryableClient interface {
+	authContext(ctx context.Context) context.Context
+	refreshJwt(ctx context.Context) error
+}


Exported interface only used internally

Low Severity

RetryableClient is exported (capitalized) but its methods authContext and refreshJwt are unexported (lowercase). This makes the interface unusable outside the package since external code cannot implement unexported methods. The interface is only used by the unexported callWithAuthRetry function, so it should be unexported as retryableClient.

cursor · 2026-01-29T01:40:39Z

modal-go/sandbox.go

+
+// SandboxTerminateParams are options for Terminate
+type SandboxTerminateParams struct {
+}


Unused parameter and empty params struct

Low Severity

SandboxTerminateParams is an empty struct and the params parameter in Terminate() is never referenced in the function body. The parameter exists but serves no purpose in the current implementation.

thomasjpfan added 2 commits January 26, 2026 17:39

Only image mount

876d3b7

Less changes

2caf2ba

cursor bot reviewed Jan 26, 2026

View reviewed changes

modal-go/sandbox.go Show resolved Hide resolved

ehdr reviewed Jan 27, 2026

View reviewed changes

thomasjpfan added 3 commits January 27, 2026 12:02

Introduce detach back

ffe8c14

Make sure terminate actually calls terminate

1175ead

Remove the need for ALPN workaround

4cb11a9

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/task_command_router_client.go Show resolved Hide resolved

modal-go/sandbox.go Outdated Show resolved Hide resolved

Add docs

a994b38

thomasjpfan changed the title ~~sandbox: dynamic directory mount & snapshot fully - Go~~ sandbox: dynamic directory mount & snapshot in go + adds detach Jan 27, 2026

thomasjpfan added 3 commits January 27, 2026 12:36

Fix lint

0a07097

Simplify tls implemetnation

42a301a

Give terminate error a higher priority

812a561

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-js/src/sandbox.ts Outdated Show resolved Hide resolved

modal-go/config.go Outdated Show resolved Hide resolved

modal-go/task_command_router_client.go Outdated Show resolved Hide resolved

Make diff smaller

9c89b64

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/examples/sandbox-image-mount/main.go Show resolved Hide resolved

modal-go/errors.go Show resolved Hide resolved

modal-go/task_command_router_client.go Outdated Show resolved Hide resolved

thomasjpfan added 4 commits January 27, 2026 14:13

Less diff

5dc47e5

Ensure that sandbox is attached before running any operation

982ccc2

Less diff

6c3a2a8

Remove ts detach

3eba12d

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/test/sandbox_test.go Outdated Show resolved Hide resolved

modal-go/test/sandbox_mount_image_test.go Outdated Show resolved Hide resolved

Allow for terminate to happen

b37410f

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/sandbox.go Outdated Show resolved Hide resolved

thomasjpfan added 2 commits January 27, 2026 16:49

Use two mutexes

d06531d

Use atomic bool

367125b

saltzm reviewed Jan 28, 2026

View reviewed changes

modal-go/config.go Outdated Show resolved Hide resolved

saltzm reviewed Jan 28, 2026

View reviewed changes

thomasjpfan added 3 commits January 28, 2026 16:55

Remove profile.TaskCommandRouterInsecure

831f1dd

Terminate no longer detaches

7365519

Add detach everywhere

f9c6f6c

cursor bot reviewed Jan 28, 2026

View reviewed changes

modal-go/examples/sandbox-filesystem-snapshot/main.go Outdated Show resolved Hide resolved

modal-go/examples/sandbox-image-mount/main.go Show resolved Hide resolved

thomasjpfan added 3 commits January 28, 2026 19:02

Update examples

10db500

Add changelog

c395951

Add example to readme

e49f593

cursor bot reviewed Jan 28, 2026

View reviewed changes

modal-go/examples/sandbox-image-mount/main.go Outdated Show resolved Hide resolved

modal-go/sandbox.go Show resolved Hide resolved

Add ensureAttached to be extra safe

ec85b2b

saltzm approved these changes Jan 28, 2026

View reviewed changes

thomasjpfan added 6 commits January 28, 2026 19:26

Use a better error message

11b08c3

Add detach and params to Sandbox.Terminate

fb06f43

Update changelog

a4a0084

Fix linter

f08632d

Do not detach

ac9e6f0

Add terminate back in

4c46034

cursor bot reviewed Jan 29, 2026

View reviewed changes

sandbox: dynamic directory mount & snapshot in go + adds detach #246

Are you sure you want to change the base?

sandbox: dynamic directory mount & snapshot in go + adds detach #246

Conversation

thomasjpfan commented Jan 26, 2026

Uh oh!

cursor bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

ehdr Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

thomasjpfan commented Jan 27, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thomasjpfan commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

saltzm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saltzm Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Deferred terminate fails after manual detach in examples

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Duplicated retryable gRPC status codes map

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Exported interface only used internally

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Unused parameter and empty params struct

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cursor bot commented Jan 26, 2026 •

edited

Loading

thomasjpfan commented Jan 27, 2026 •

edited

Loading