Go SDK Reference

This is the API reference for the Modal Go SDK.

Installing 

Install the library using go get:

go get github.com/modal-labs/modal-client/go@latest

Then you can import it in your code:

import modal "github.com/modal-labs/modal-client/go"

Go 1.24.0 or later is required.

Configuration 

A Modal API token / secret pair is required for authentication. Credentials are read from the following sources in descending order of precedence:

• Parameters passed when constructing a new Client
• MODAL_TOKEN_ID and MODAL_TOKEN_SECRET environment variables
• token_id and token_secret fields in the active profile of a ~/.modal.toml file

API tokens can be created in the workspace settings on the Modal Dashboard.

Tokens can also be created and managed with the Modal CLI. The CLI is packaged with the Python SDK, but it can also be installed as a standalone tool:

curl -LsSf uvx.sh/modal/install.sh | sh

Objects 

Scope 

The Go SDK is more limited in scope than Modal’s Python SDK. Namely, Python remains the only supported Function runtime, so features for defining Functions are not available in Go. We do aim to support most interactions with remote Modal objects, including Functions, Sandboxes, Volumes, and others. Some in-scope features are not yet implemented; please get in touch if these are important to you.

Usage 

Instances of the Modal Object types are obtained through service methods on the Client type.

mc, err := modal.NewClient()
if err != nil {
  log.Fatal(err)
}
defer mc.Close()

Interaction with instances of the Modal Objects happens via methods on those instances. All methods have an associated Params struct for passing optional arguments.

Sandbox 

The Go SDK aims to support the complete feature-set for Modal Sandboxes:

app, err := mc.Apps.FromName(ctx, "sandbox-app", &modal.AppFromNameParams{CreateIfMissing: true})
if err != nil {
	log.Fatal(err)
}
image := mc.Images.FromRegistry("alpine:3.21", nil)

sb, err := mc.Sandboxes.Create(ctx, app, image, nil)
if err != nil {
	log.Fatal(err)
}
defer sb.Terminate(ctx, nil)

p, err := sb.Exec(ctx, []string{"echo", "Hello from a Sandbox!"}, nil)
if err != nil {
	log.Fatal(err)
}
output, err := io.ReadAll(p.Stdout)
if err != nil {
	log.Fatal(err)
}
fmt.Print(string(output))

Sandboxes accept many additional parameters at creation time for configuring their resources, lifecycle, restrictions, etc.:

secret, err := mc.Secrets.FromName(ctx, "github-token", nil)
if err != nil {
	log.Fatal(err)
}

sb, err := mc.Sandboxes.Create(ctx, app, image, &modal.SandboxCreateParams{
	Secrets:                 []*modal.Secret{secret},
	Timeout:                 30 * time.Minute,
	CPU:                     2,
	MemoryMiB:               2048,
	OutboundDomainAllowlist: &modal.Allowlist{Entries: []string{"github.com", "*.githubusercontent.com"}},
})
if err != nil {
	log.Fatal(err)
}
defer sb.Terminate(ctx, nil)

Function 

Modal Functions in deployed Apps can be looked up and invoked from Go programs:

f, err := mc.Functions.FromName(ctx, "my-app", "echo", nil)
if err != nil {
	log.Fatal(err)
}

result, err := f.Remote(ctx, []any{"Hello, Modal!"}, nil)

var remoteErr modal.RemoteError
if errors.As(err, &remoteErr) {
	log.Fatalf("remote call failed: %s", remoteErr.Exception)
} else if err != nil {
	log.Fatal(err)
}

response, ok := result.(string)
if !ok {
	log.Fatalf("expected a string result, got %T", result)
}
fmt.Println(response)

All Function invocation methods are available:

fc, err := f.Spawn(ctx, []any{"Hello, Modal!"}, nil)
if err != nil {
	log.Fatal(err)
}

result, err := fc.Get(ctx, nil)
if err != nil {
	log.Fatal(err)
}
fmt.Println(result)

Errors 

Error types are documented on the Errors page. Errors are returned as values and implement the standard error interface; use errors.As to match them.

Versioning 

Go SDK releases use semantic versioning. The library is currently in a beta (0.X) state. Breaking changes may be included in 0.X.0 releases.