Modal logo
Go SDK Reference Allowlist App Client CloudBucketMount Cls ClsInstance ContainerProcess Errors FileInfo FileType FileWatchEvent FileWatchEventType Function FunctionAutoscalerSettings FunctionCall FunctionStats Image LogEntry LogSource Probe Profile Proxy Queue Retries Sandbox SandboxCreateConnectCredentials SandboxSnapshot Secret SidecarContainer StdioBehavior Tunnel Volume

Go SDK Release Notes

Latest 

0.10.1 (2026-09-10) 

  • It’s now possible to opt into a more performant Sandbox backend by setting a MODAL_SANDBOX_V2=1 environment variable or a sandbox_v2 = true profile configuration in .modal.toml. Sandboxes will then use the new backend without any code changes. This will become the default behavior in an upcoming release; setting the flag lets you opt in early.
  • The client now releases the connection to a Sandbox host when the connection is idle and automatically reconnects on subsequent operations, so it is no longer necessary to call Sandbox.Detach() for resource cleanup.

0.10.0 (2026-08-27) 

  • Added Function.Logs and FunctionCall.Logs APIs for fetching current and historical logs generated by that object. The Logs namespace exposes three methods: use Fetch for time-based queries, Tail for returning the most recent entries, or Stream for yielding entries as they arrive.
  • Sandbox.Filesystem.CopyFromLocal / WriteBytes / WriteText now stream data to the Sandbox instead of issuing a request per chunk, making large writes ~2.5× faster.
  • Function.UpdateAutoscaler now returns a struct containing the current autoscaler settings immediately after applying the change.
  • Breaking: Unexported AuthTokenManager, NewAuthTokenManager, TokenAndExpiry, and ValidateExecArgs which were not meant to be part of the public API.
  • Breaking: FunctionUpdateAutoscalerParams.ScaledownWindow is now typed as a *time.Duration instead of as a *uint32.

0.9 

0.9.0 (2026-07-09) 

  • Functions.FromName and Cls.FromName now accept an optional Version parameter to look up a version-pinned Function or Cls.
  • Secrets.FromMap is now lazy, so the returned Secret has an empty SecretID until it is first used. Latency for Sandbox.ExperimentalCreate and Sandbox.Exec is improved by sending the secrets directly to the Sandbox and avoiding the secret creation limits.
  • Function.WithOptions and Cls.WithOptions now accept a RoutingRegion option to override the region the Function’s or Cls’s inputs and outputs are routed through.
  • Added Sandbox.Filesystem.Watch to watch a path in the Sandbox for filesystem changes. It yields FileWatchEvent objects and supports Recursive, an event-type Filter, and a Timeout bound.
  • Breaking: Sandbox.ReloadVolumes now blocks until the Volumes have been reloaded, bounded by a new timeout (55 seconds by default) that is configurable via SandboxReloadVolumesParams.Timeout. If the reload does not complete within that window, a TimeoutError is raised.
  • Breaking: Renamed the VolumeMountOptions type to VolumeMountOptionsParams. Update WithMountOptions(&VolumeMountOptions{...}) call sites accordingly.
  • Breaking: Changed OutboundCIDRAllowlist and OutboundDomainAllowlist in SandboxCreateParams from []string to *Allowlist. A non-nil *Allowlist enables allowlist mode (even with empty Entries, which blocks all traffic of that type); nil means open access. Migrate OutboundCIDRAllowlist: []string{"10.0.0.0/8"} to OutboundCIDRAllowlist: &Allowlist{Entries: []string{"10.0.0.0/8"}}.

0.8 

0.8.2 (2026-06-29) 

  • Added Sandbox.UpdateNetworkPolicy to update the outbound network policy of a running Sandbox. Both OutboundCIDRAllowlist and OutboundDomainAllowlist must be provided.

0.8.1 (2026-06-25) 

  • Sandbox.CreateConnectToken now accepts an optional Port parameter on its params struct, controlling which container port requests are routed to when using the token. Defaults to 8080.

0.8.0 (2026-06-10) 

This release primarily contains a number of breaking changes as we continue working towards 1.0.

  • Added support for named Images, akin to a Modal-native Image registry, decoupling Image builds from App deployment or Sandbox creation, via Image.Publish and Image.FromName.
  • Added support for restricting the domains that processes inside of a Sandbox can connect to, via OutboundDomainAllowlist in SandboxCreateParams.
  • Added support for dynamic configuration of Functions: Function.WithOptions, Function.WithConcurrency, Function.WithBatching, and Function.Instance.
  • Improved reliability when uploading or downloading large data payloads for Function calls.
  • Fixed a bug where adding Dockerfile commands to an Image loaded with Image.FromID could fail to use the resolved Image as the base.
  • Sandbox.Exec now rejects a relative Workdir client-side with InvalidError.
  • Sandbox.Create and Sandbox.Exec now return an InvalidError if any Secrets entry is nil.
  • Breaking: The Go SDK now reads the Image Builder Version from your Modal workspace settings, like the Python SDK. Previously, the Go SDK was hardcoded to use version 2024.10. If your workspace configuration uses a different version, your Images will rebuild once (then be cached as usual), so beware that the first run after upgrading may take longer than usual. Note that version 2025.06 has a number of improvements that are specifically oriented towards Sandbox workflows.
  • Breaking: Sandbox.SnapshotFilesystem no longer takes a positional timeout argument. The timeout now lives on the params struct as Timeout time.Duration, bringing the method to parity with Sandbox.SnapshotDirectory. Migrate sb.SnapshotFilesystem(ctx, 30*time.Second, params) to sb.SnapshotFilesystem(ctx, &SandboxSnapshotFilesystemParams{Timeout: 30*time.Second, ...}).
  • Breaking: Sandbox.SnapshotFilesystem and Sandbox.SnapshotDirectory now accept an explicit TTL field (a time.Duration) on their params structs, controlling how long the resulting Image is retained. Both methods default to 30 days. This is a change of default for SnapshotFilesystem, which previously kept Images indefinitely. Pass TTL: modal.NoExpiryTTL to opt out of expiry.
  • Breaking: Sandbox.SnapshotDirectory now also has a Timeout field on its params struct with a default of 55s, which brings it to parity with filesystem snapshots. If the snapshot does not return within that window, a TimeoutError is raised. The timeout can be set arbitrarily high to preserve the old behavior of not timing out.
  • Breaking: Sandbox.Filesystem is now a field rather than a method. Migrate sb.Filesystem().ReadText(...) to sb.Filesystem.ReadText(...).
  • Breaking: Sandbox.FromID no longer checks if the sandbox ID exists. You can run Poll to get the status of your sandbox.
  • Breaking: Removed the deprecated low-level file-handle API: Sandbox.Open and SandboxFile. Use the Sandbox Filesystem API instead: sandbox.Filesystem.
  • Breaking: Removed the deprecated Volume.ReadOnly and Volume.IsReadOnly. Use WithMountOptions(&VolumeMountOptions{ReadOnly: &t}) instead.
  • Breaking: All public methods now end with a *XxxParams pointer argument, enabling forward-compatibility for future options without additional signature churn. Pass nil to accept defaults. Affected methods:

0.7 

0.7.6 (2026-05-21) 

  • Added the Sandbox Filesystem API, available via sandbox.Filesystem(). The filesystem API contains methods:
    • fs.WriteText: Write UTF-8 to a file in the Sandbox.
    • fs.WriteBytes: Write binary content to a file in the Sandbox.
    • fs.ReadText: Read a file from the Sandbox and return its contents as a UTF-8 string.
    • fs.ReadBytes: Read a file from the Sandbox and return its contents as bytes.
    • fs.MakeDirectory: Create a new directory in the Sandbox.
    • fs.ListFiles: List files and directories in a Sandbox directory.
    • fs.Stat: Return metadata for a single file, directory, or symlink in the Sandbox.
    • fs.CopyFromLocal: Copy a local file into the Sandbox.
    • fs.CopyToLocal: Copy a file from the Sandbox to a local path.
    • fs.Remove: Remove a file or directory in the Sandbox.
  • Added Volume.WithMountOptions to configure mount-time options (ReadOnly and SubPath) when attaching a Volume to a Function or Sandbox. The SubPath option mounts a subdirectory of the Volume instead of its root. Calling WithMountOptions multiple times on the same Volume stacks: fields left unset preserve their previous value.
  • Deprecated Volume.ReadOnly in favor of WithMountOptions(&VolumeMountOptions{ReadOnly: &t}). The old method still works but will be removed in a future release.
  • Deprecated Volume.IsReadOnly; track configured mount options at the call site that configured them instead.

0.7.5 (2026-05-19) 

  • We’ve improved the reliability of the Sandbox.SnapshotFilesystem operation, especially for large snapshots, and we now support setting a Timeout longer than 55s when necessary.
  • Added Sandbox.UnmountImage to remove an image mount from a path in the Sandbox filesystem and reveal the underlying directory again.
  • Sandboxes.Create now accepts a Tags parameter to attach key-value tags to the Sandbox at creation time.
  • Sandboxes.Create now accepts an InboundCIDRAllowlist parameter to restrict which source IPs can connect inbound to a sandbox’s tunnels and connection tokens.
  • Renamed CIDRAllowlist to OutboundCIDRAllowlist to distinguish from the corresponding inbound allowlist.
  • The Go SDK can now respond more gracefully to server throttling (e.g., rate limiting) by backing off and automatically retrying.

0.7.4 (2026-04-03) 

  • Sandboxes.Create now accepts an IncludeOidcIdentityToken parameter. When enabled, a MODAL_IDENTITY_TOKEN environment variable is injected into the sandbox, enabling OIDC-based authentication (e.g., for AWS federation).
  • We’re introducing a concept of “readiness probes” for Sandbox. This feature lets you configure a readiness check on a TCP port, with NewTCPProbe, or by executing a process, with NewExecProbe. Calling sb.WaitUntilReady() will block until the Probe succeeds.

0.7.3 (2026-03-12) 

  • Migrated the SDK from github.com/modal-labs/libmodal to github.com/modal-labs/modal-client.

0.7.2 (2026-02-26) 

  • Updated Sandbox methods to wait for newly created sandboxes to be ready and not error immediately when it’s not available yet.

0.7.1 (2026-02-23) 

  • No changes affecting the Go SDK.

0.7.0 (2026-02-23) 

  • Added Sandbox.MountImage, which mounts an Image to a path in the Sandbox’s filesystem.
  • Added Sandbox.SnapshotDirectory, which snapshots a directory in the running sandbox and creates a new Image from it.
  • Upgraded Sandbox.Exec, bringing improved performance and reliability.
  • Added a Sandbox.Detach to disconnect your client from the sandbox and clean up any resources associated with the connection. We strongly recommend calling Detach after you are done interacting with the sandbox. Detach does not close streams from Sandbox.Stdout. These streams should be closed using their Close method.
  • Sandbox.Terminate detaches by default. To interact with a running sandbox, use Sandboxes.FromID to create a new Sandbox object.
  • Sandbox.Terminate now accepts a Wait parameter to wait for the sandbox to terminate and return the exit code.

Breaking changes:

  • Changed Sandbox.Terminate, which now returns (int, error). The int is the return code when &SandboxTerminateParams{Wait: true} is passed in.
  • Added a Sandbox.Detach to disconnect your client from the sandbox and clean up any resources associated with the connection. We strongly recommend calling Detach after you are done interacting with the sandbox.

0.6 

0.6.3 (2026-02-18) 

  • Fixed a bug where deleting a Volume, Queue, or Secret with AllowMissing: true could still raise a NOT_FOUND error.
  • Improved handling of degraded HTTP/2 connections, which addresses intermittent RST_STREAM errors.

0.6.2 (2026-02-09) 

  • No changes affecting the Go SDK.

0.6.1 (2026-01-30) 

  • Added custom domains to Sandboxes.Create. Note that Sandbox custom domains work differently from Function custom domains and must currently be set up manually by Modal; please get in touch if this feature interests you.

0.6.0 (2025-12-10) 

  • Added enable_docker experimental option to Sandbox.Create.

0.5 

0.5.6 (2025-12-02) 

0.5.5 (2025-11-25) 

  • Enabled goroutine leak detection for all tests by default.
  • Fixed a few remaining goroutine leaks.
  • Test clean-ups: ensure we always terminate Sandboxes, close ephemeral objects, etc.
  • Added debug logging to CloudBucketMount creation, bringing it in line with the JS SDK.
  • Aligned the way the Go SDK handles empty/missing fields in gRPC messages, so the behavior is identical to the Python SDK.

0.5.4 (2025-11-10) 

  • Enabled goleak for goroutine leak detection in tests.
  • Fixed all detected goroutine leaks in Sandboxes and Images.
  • Added deletion methods for Volume and Secret objects and updated the deletion methods on Queue objects to support idempotent deletion via the AllowMissing parameter.

0.5.3 (2025-11-08) 

  • Fixed a bug where Sandbox.Exec would leak goroutines.

0.5.2 (2025-11-04) 

  • Allow adding custom gRPC interceptors when creating a Modal client, to allow instrumentation, custom telemetry, etc.

0.5.1 (2025-11-03) 

  • All Go SDK functions that take a Context will respect the timeout of the context.
  • Improved the error message when calling a webhook Function as a normal Function.
  • Allow customizing the config file path via MODAL_CONFIG_PATH environment variable (defaults to ~/.modal.toml).
  • Added support for passing MODAL_LOGLEVEL=debug environment variable to also log debug logs, incl. all gRPC calls, etc.

0.5.0 (2025-10-28) 

The first beta release of the Modal SDK for Go (graduating from alpha). See the Migration Guide for a detailed list of breaking changes.

  • The SDK now exposes a central Client object as the main entry point for interacting with Modal resources.
  • The interface for working with Modal object instances (Functions, Sandboxes, Images, etc.) is largely the same as before, with some naming changes.
  • Calling deployed Functions and classes now uses a new protocol for payload serialization which requires the deployed apps to use the Modal Python SDK 1.2 or newer.
  • Internally removed the global client (and config/profile data in global scope), moving all that to the Client type.
  • Consistent parameter naming across the Go and JS SDKs: all Options structs renamed to Params.
  • Changed how we do context passing, so contexts now only affect the current operation and are not used for lifecycle management of the created resources.
  • All Params structs are now passed as pointers for consistency and to support optional parameters.
  • Field names follow Go casing conventions (e.g., Id → ID, Url → URL, TokenId → TokenID).
  • Added explicit unit suffixes to all parameters that represent memory amounts (in MiB, suffixed with MiB).

Additional new features:

  • Added support for setting CPU and memory limits when creating Sandboxes and Cls instances.

0.0 

0.0.25 (2025-10-08) 

  • Internal updates for how authentication tokens are handled for input plane clients.

0.0.24 (2025-09-19) 

  • Added an Env parameter to several methods, as a convenience for passing environment variables into Sandboxes, etc.
  • Added Sandbox.GetTags().

0.0.23 (2025-09-15) 

  • Added support for PTYs in Sandboxes.

0.0.22 (2025-09-11) 

0.0.21 (2025-09-08) 

  • Added support for setting idle timeout when creating Sandboxes.

0.0.20 (2025-09-02) 

  • Added ImageDelete().
  • Changed NewImageFromId() to return a NotFoundError if the Image does not exist. Note that the signature of NewImageFromId() has changed.

0.0.19 (2025-08-26) 

  • No changes affecting the Go SDK.

0.0.18 (2025-08-26) 

0.0.17 (2025-08-22) 

  • Added support for more parameters to Sandbox.Create():
    • BlockNetwork: Whether to block all network access from the Sandbox.
    • CIDRAllowlist: List of CIDRs the Sandbox is allowed to access.
    • GPU: GPU reservation for the Sandbox (e.g. “A100”, “T4:2”, “A100-80GB:4”).
    • Cloud: Cloud provider to run the Sandbox on.
    • Regions: Region(s) to run the Sandbox on.
    • Verbose: Enable verbose logging.
    • Proxy: Connect a Modal Proxy to a Sandbox.
    • Workdir: Set the working directory.
  • Added support for mounting CloudBucketMounts to Sandboxes.
  • Added top-level Image objects that are lazy. The Images are built when creating a Sandbox.
    • NewImageFromRegistry
    • NewImageFromAwsEcr
    • NewImageFromGcpArtifactRegistry
  • Added SecretFromMap() to create a Secret from key-value pairs (like from_dict() in Python).
  • Added Name field to Apps, Sandboxes, Secrets, Volumes, and Queues.
  • Added support for Function.GetCurrentStats().
  • Added support for Function.UpdateAutoscaler().
  • Added support for Function.GetWebURL().
  • Added support for Volume.ReadOnly().
  • Added support for setting tags on Sandboxes, and for listing Sandboxes (by tag).

0.0.16 (2025-08-07) 

0.0.15 (2025-07-23) 

0.0.14 (2025-07-07) 

  • Added support for setting up Tunnels to expose live TCP ports for Sandboxes.

0.0.13 (2025-07-03) 

  • Fixed calls of Cls with experimental input_plane_region option.
  • Removed Function.InputPlaneURL from being exposed as public API.

0.0.12 (2025-07-02) 

  • Added support for passing a Secret to ImageFromRegistry() to pull images from private registries.
  • Added support for creating Images from Google Artifact Registry with ImageFromGcpArtifactRegistry().
  • Added experimental support for calling remote Functions deployed with the input_plane_region option in Python.

0.0.11 (2025-06-30) 

  • Added InitializeClient() to initialize the client at runtime with credentials.
  • The client library no longer panics at startup if no token ID / Secret is provided. Instead, it will return an error when trying to use the client.

0.0.10 (2025-06-28) 

  • Added Workdir and Timeout options to ExecOptions for Sandbox processes.

0.0.9 (2025-06-27) 

  • Added support for Sandbox filesystem.

0.0.8 (2025-06-18) 

  • Added support for creating Images from AWS ECR with App.ImageFromAwsEcr().
  • Added support for accessing Modal Secrets with modal.SecretFromName().

0.0.7 (2025-06-09) 

  • Added support for the Queue object to manage distributed FIFO queues.
    • Queues have a similar interface as Python, with Put() and Get() being the primary methods.
    • You can put structured objects onto Queues, with limited support for the pickle format.
  • Added InvalidError, QueueEmptyError, and QueueFullError to support Queues.
  • Options in the Go SDK now take pointer types, and can be nil for default values.

0.0.6 (2025-05-30) 

0.0.5 (2025-05-03) 

  • Added feature for looking up and calling remote classes via the Cls object.
  • Removed the initial ctx context.Context argument from Function.Remote().

0.0.4 (2025-05-02) 

  • Support calling remote Functions with arguments greater than 2 MiB in byte payload size.

0.0.3 (2025-04-29)