Skip to main content
The Modal TypeScript SDK is available as an npm package and works with Node.js, Deno, and Bun.

​
Install the package

Install the Modal SDK in any server-side Node.js, Deno, or Bun project: 
npm install modal
View the package on npm: https://www.npmjs.com/package/modal

​
Requirements

The Modal TypeScript SDK requires Node.js 22 or later.
The SDK bundles both ES Modules and CommonJS formats, so you can load the package with either import or require() in any project:
ES Modules
import { ModalClient } from "modal";

const modal = new ModalClient();
CommonJS
const { ModalClient } = require("modal");

const modal = new ModalClient();

​
Authentication

You need to authenticate with Modal before using the SDK. There are two methods: The easiest way to authenticate is using the Modal CLI:
1

Install Modal Python SDK

pip install modal
2

Run the setup command

modal setup
This will:
  • Open your browser to authenticate
  • Create a ~/.modal.toml configuration file with your credentials
  • Set up the default profile
3

Verify authentication

Your TypeScript SDK will automatically use the credentials from ~/.modal.toml:
import { ModalClient } from "modal";

const modal = new ModalClient();
// Automatically uses credentials from ~/.modal.toml

​
Method 2: Environment variables

For machine environments (CI/CD, production servers), use environment variables:
1

Get your Modal tokens

  1. Go to https://modal.com/settings/tokens
  2. Create a new token
  3. Copy your token_id and token_secret
2

Set environment variables

export MODAL_TOKEN_ID=ak-YOUR_TOKEN_ID
export MODAL_TOKEN_SECRET=as-YOUR_TOKEN_SECRET
Keep your token secret secure! Never commit it to version control.
3

Use in your code

The SDK will automatically detect the environment variables:
import { ModalClient } from "modal";

const modal = new ModalClient();
// Automatically uses MODAL_TOKEN_ID and MODAL_TOKEN_SECRET

​
Configuration

The Modal SDK uses configuration from several sources, in order of priority:
  1. Constructor parameters: Passed directly to new ModalClient()
  2. Environment variables: MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, etc.
  3. Configuration file: ~/.modal.toml (default) or custom path via MODAL_CONFIG_PATH

​
Configuration file location

The default configuration file is ~/.modal.toml. You can customize this: 
export MODAL_CONFIG_PATH=/path/to/custom/config.toml

​
Available environment variables

VariableDescriptionDefault
MODAL_TOKEN_IDYour Modal token ID-
MODAL_TOKEN_SECRETYour Modal token secret-
MODAL_ENVIRONMENTEnvironment name-
MODAL_SERVER_URLModal API server URLhttps://api.modal.com:443
MODAL_CONFIG_PATHPath to config file~/.modal.toml
MODAL_PROFILEProfile name to useActive profile in config
MODAL_IMAGE_BUILDER_VERSIONImage builder version2024.10
MODAL_LOGLEVELLogging level-

​
Verify installation

Create a simple test script to verify your installation:
test.ts
import { ModalClient } from "modal";

const modal = new ModalClient();

const app = await modal.apps.fromName("test-app", {
  createIfMissing: true,
});

const image = modal.images.fromRegistry("alpine:3.21");

const sb = await modal.sandboxes.create(app, image, {
  command: ["echo", "Hello from Modal!"],
});

console.log("Output:", await sb.stdout.readText());
await sb.terminate();

console.log("✓ Modal SDK is working!");
Run the test: 
node test.ts
If everything is set up correctly, you should see: 
Output: Hello from Modal!
✓ Modal SDK is working!

​
Next steps

Basic usage

Learn basic patterns and workflows

Client configuration

Configure the ModalClient

Build docs developers (and LLMs) love

Get started for freeTalk to us