ModalClient

The main client for interacting with Modal’s cloud infrastructure

The ModalClient class is the primary entry point for all interactions with Modal’s cloud services. It provides access to all Modal resources through service properties.

Constructor

new ModalClient(params?)

Creates a new Modal client instance.

params · ModalClientParams

Configuration options for the client

Show properties

tokenId · string

Modal API token ID. If not provided, uses MODAL_TOKEN_ID environment variable or value from .modal.toml.

tokenSecret · string

Modal API token secret. If not provided, uses MODAL_TOKEN_SECRET environment variable or value from .modal.toml.

environment · string

Environment name to use. Defaults to the workspace default environment.

endpoint · string

Custom server endpoint URL.

timeoutMs · number

Default timeout for API calls in milliseconds.

maxRetries · number

Maximum number of retries for transient failures.

logger · Logger

Custom logger instance.

logLevel · LogLevel

Log level: "debug", "info", "warn", or "error". Defaults to "warn".

grpcMiddleware · ClientMiddleware[]

Custom gRPC middleware for advanced observability. These are appended after Modal’s built-in middleware.

The Modal gRPC API is not considered a public API and can change without warning.

import { ModalClient } from "modal";

// Use default credentials from environment or .modal.toml
const modal = new ModalClient();

// Or provide explicit credentials
const modal = new ModalClient({
  tokenId: "ak-...",
  tokenSecret: "as-...",
  environment: "staging",
});

Service properties

The ModalClient instance provides access to all Modal services through the following properties:

apps · AppService

Service for managing Apps. See Apps API.

functions · FunctionService

Service for managing Functions. See Functions API.

cls · ClsService

Service for managing Classes. See Cls API.

images · ImageService

Service for managing container images. See Images API.

sandboxes · SandboxService

Service for managing Sandboxes. See Sandboxes API.

volumes · VolumeService

Service for managing persistent Volumes. See Volumes API.

queues · QueueService

Service for managing distributed Queues. See Queues API.

secrets · SecretService

Service for managing Secrets. See Secrets API.

functionCalls · FunctionCallService

Service for managing Function calls.

proxies · ProxyService

Service for managing Proxies.

cloudBucketMounts · CloudBucketMountService

Service for managing cloud bucket mounts.

Methods

close()

Closes the client and cleans up resources. After calling this method, the client should not be used.

const modal = new ModalClient();

// Use the client...

modal.close();

version()

Returns the SDK version string.

return · string

The version of the Modal JavaScript SDK.

const modal = new ModalClient();
console.log(modal.version()); // e.g., "0.5.0"

Example usage

import { ModalClient } from "modal";

const modal = new ModalClient();

// Get or create an app
const app = await modal.apps.fromName("my-app", {
  createIfMissing: true,
});

// Create an image from a registry
const image = modal.images.fromRegistry("python:3.13");

// Create a sandbox
const sb = await modal.sandboxes.create(app, image, {
  timeoutMs: 300000,
  memoryMiB: 2048,
});

// Execute a command
const proc = await sb.exec(["python", "--version"]);
const output = await proc.stdout.readText();
console.log(output);

// Clean up
await sb.terminate();
modal.close();