Modal Client SDKs

Modal provides SDKs for JavaScript/TypeScript and Go. These SDKs allow you to:

• Use Modal Sandboxes
• Invoke deployed Modal Functions
• Interact with various Modal platform resources.

When using Cls (serverless classes), you can manage how they are initialized and how they behave during their lifecycle:

• parameter: Define class parameters similarly to a Python dataclass field.
• enter: A decorator for a method that executes during container startup.
• exit: A decorator for a method that executes during container shutdown.
• method: A decorator used to expose a specific class method as an invokable function.

Enhance function execution behavior with these decorators and configurations:

• batched: Enables dynamic input batching to optimize throughput.
• concurrent: Enables input concurrency to process multiple inputs simultaneously.
• Retries: A policy used to define how functions should retry upon input failures.

To deploy code to Modal, you must first define an App. The App serves as the main unit of deployment. You register your code components (functions, classes, or servers) to an App using specific decorators:

• App.function: Decorator to register a standalone function.
• App.cls: Decorator to register a class.
• App.server: Decorator to register a server.

For restricted or isolated code execution, use the Sandbox interface. The Sandbox provides:

• Sandbox: The primary interface for restricted execution.
• ContainerProcess: An object representing a specific process running within the sandbox.
• FileIO: A handle used to interact with the filesystem inside the Sandbox.

The SDK provides access to several core Modal abstractions through the ModalClient:

• App: The main unit of deployment for code on Modal.
• Function: A serverless function backed by an autoscaling container pool.
• Image: An immutable representation of a container filesystem.
• Sandbox: A process-like interface for restricted execution.
• Secret: A secure reference to environment variables.
• Volume: A mutable distributed storage device.

You can expose your functions as web endpoints using several decorators depending on your web framework or protocol:

• fastapi_endpoint: Exposes a simple FastAPI-based endpoint.
• asgi_app: For functions that construct an ASGI web application.
• wsgi_app: For functions that construct a WSGI web application.
• web_server: For functions that construct a standard HTTP web server.

Modal provides several primitives for data handling:

Persistent Storage

• Volume: Distributed storage optimized for high-performance parallel reads/writes.
• CloudBucketMount: Storage backed by third-party cloud buckets (e.g., S3).

In-memory Storage

• Dict: A distributed key-value store.
• Queue: A distributed FIFO (First-In-First-Out) queue.

Define the environment in which your code runs:

• Image: An API for specifying and building container images.
• Secret: A pointer to secrets that are injected into the container as environment variables.

To interact with Modal, first instantiate a ModalClient. You then obtain instances of Modal objects (like App, Image, or Sandbox) through service methods on that client. Most methods accept an options object (often with an associated Params type) for configuration.

import { ModalClient } from "modal";

const modal = new ModalClient();

A Sandbox provides a process-like interface for restricted execution. You obtain a Sandbox by calling mc.Sandboxes.Create using an App and an Image.

Key features:

• Execution: Use sb.Exec to run commands. It returns a process object containing Stdout and Stderr.
• Configuration: You can configure resources like CPU, MemoryMiB, Timeout, and Secrets using SandboxCreateParams.
• Lifecycle: Always call sb.Terminate(ctx, nil) to end the sandbox session.

// Basic Sandbox usage
app, err := mc.Apps.FromName(ctx, "sandbox-app", &modal.AppFromNameParams{CreateIfMissing: true})
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!"}, nil)
// ... read output