Skip to main content
The Modal client is the main entry point for interacting with Modal resources in Go.

​
Creating a client

​
NewClient

Creates a new Modal client with default configuration from environment variables and ~/.modal.toml. 
import "github.com/modal-labs/modal-client/go"

mc, err := modal.NewClient()
if err != nil {
    // Handle error
}
defer mc.Close()
Returns:
  • *Client - The Modal client instance
  • error - Error if initialization fails

​
NewClientWithOptions

Creates a new Modal client with custom configuration. 
mc, err := modal.NewClientWithOptions(&modal.ClientParams{
    TokenID:     "ak-...",
    TokenSecret: "as-...",
    Environment: "main",
})
if err != nil {
    // Handle error
}
defer mc.Close()
​
params
*ClientParams
Client configuration parameters
​
TokenID
string
Modal token ID (overrides config file)
​
TokenSecret
string
Modal token secret (overrides config file)
​
Environment
string
Environment name (e.g., “main”, “dev”)
​
Config
*config
Custom config object (advanced usage)
​
Logger
*slog.Logger
Custom logger instance
​
ControlPlaneClient
pb.ModalClientClient
Custom gRPC client for testing
​
ControlPlaneConn
*grpc.ClientConn
Underlying gRPC connection for ControlPlaneClient
​
GRPCUnaryInterceptors
[]grpc.UnaryClientInterceptor
Custom gRPC unary interceptors for telemetry and observability
​
GRPCStreamInterceptors
[]grpc.StreamClientInterceptor
Custom gRPC stream interceptors for telemetry and observability
Returns:
  • *Client - The Modal client instance
  • error - Error if initialization fails

​
Client methods

​
Close

Closes all gRPC connections. Should be called when done using the client. 
mc.Close()

​
Version

Returns the SDK version. 
version := mc.Version()
fmt.Println("SDK version:", version)
Returns:
  • string - The SDK version string

​
Client services

The client exposes the following services for interacting with Modal resources:
​
Apps
AppService
Service for working with Modal Apps. See Apps API.
​
CloudBucketMounts
CloudBucketMountService
Service for mounting cloud storage buckets.
​
Cls
ClsService
Service for working with Modal classes. See Cls API.
​
Functions
FunctionService
Service for working with Modal Functions. See Functions API.
​
FunctionCalls
FunctionCallService
Service for working with Function Calls.
​
Images
ImageService
Service for working with Modal Images. See Images API.
​
Proxies
ProxyService
Service for working with Modal Proxies.
​
Queues
QueueService
Service for working with Modal Queues. See Queues API.
​
Sandboxes
SandboxService
Service for working with Modal Sandboxes. See Sandboxes API.
​
Secrets
SecretService
Service for working with Modal Secrets. See Secrets API.
​
Volumes
VolumeService
Service for working with Modal Volumes. See Volumes API.

​
Complete example

package main

import (
    "context"
    "fmt"
    "io"

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

func main() {
    ctx := context.Background()

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

    app, err := mc.Apps.FromName(ctx, "my-app", &modal.AppFromNameParams{
        CreateIfMissing: true,
    })
    if err != nil {
        panic(err)
    }

    image := mc.Images.FromRegistry("alpine:3.21", nil)
    
    sb, err := mc.Sandboxes.Create(ctx, app, image, nil)
    if err != nil {
        panic(err)
    }
    defer sb.Terminate(context.Background(), nil)

    p, err := sb.Exec(ctx, []string{"echo", "Hello from Modal!"}, nil)
    if err != nil {
        panic(err)
    }

    stdout, err := io.ReadAll(p.Stdout)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Output: %s\n", stdout)
}

Build docs developers (and LLMs) love

Get started for freeTalk to us