The Cls API allows you to reference deployed Modal classes and call their methods remotely.
Access the Cls API
import { ModalClient } from "modal";
const modal = new ModalClient();
const cls = await modal.cls.fromName("my-app", "MyClass");
Methods
modal.cls.fromName(appName, name, params?)
Reference a Cls from a deployed App by its name.
Name of the App containing the class.
Name of the class to reference.
Optional parameters
If true, creates the class if it doesn’t exist.
The referenced Cls object.
const cls = await modal.cls.fromName("my-app", "Model");
Cls object
The Cls object represents a deployed Modal class. You must create an instance before calling methods.
Methods
instance(parameters?)
Create an instance of the class with optional parameters.
Constructor parameters for the class. The parameter types must match the class definition.
A class instance that can be used to call methods.
const cls = await modal.cls.fromName("my-app", "Model");
// Create an instance without parameters
const instance = await cls.instance();
// Create an instance with parameters
const instance = await cls.instance({
model_name: "gpt-4",
temperature: 0.7,
});
withOptions(options)
Override the static Function configuration at runtime.
options
ClsWithOptionsParams
required
Runtime configuration options
CPU reservation in cores (can be fractional).
Memory reservation in MiB.
Memory hard limit in MiB.
GPU configuration (e.g., "A100", "T4:2").
Environment variables to set.
Secrets to inject as environment variables.
Volumes to mount at specified paths.
Retry configuration for method calls.
Maximum concurrent containers.
Buffer containers for burst capacity.
Scaledown window in milliseconds (must be a multiple of 1000).
Method execution timeout in milliseconds (must be a multiple of 1000).
A new Cls object with the specified options.
const cls = await modal.cls.fromName("my-app", "Model");
// Override GPU configuration
const clsWithGpu = cls.withOptions({
gpu: "A100",
memoryMiB: 8192,
});
const instance = await clsWithGpu.instance();
withConcurrency(params)
Create a version of the class with input concurrency enabled or overridden.
params
ClsWithConcurrencyParams
required
Concurrency configuration
Maximum number of concurrent inputs to process.
Target number of concurrent inputs (for autoscaling).
A new Cls object with concurrency enabled.
const cls = await modal.cls.fromName("my-app", "Worker");
const clsConcurrent = cls.withConcurrency({
maxInputs: 10,
targetInputs: 5,
});
const instance = await clsConcurrent.instance();
withBatching(params)
Create a version of the class with dynamic batching enabled or overridden.
params
ClsWithBatchingParams
required
Batching configuration
Time to wait in milliseconds before processing a partial batch.
A new Cls object with batching enabled.
const cls = await modal.cls.fromName("my-app", "Embedder");
const clsBatched = cls.withBatching({
maxBatchSize: 32,
waitMs: 100,
});
const instance = await clsBatched.instance();
ClsInstance object
Represents an instance of a deployed Modal class.
Methods
method(name)
Get a reference to a class method.
Name of the method to call.
A Function object that can be invoked with remote() or spawn().
const cls = await modal.cls.fromName("my-app", "Model");
const instance = await cls.instance();
const generateMethod = instance.method("generate");
const result = await generateMethod.remote(["Hello world"]);
Example: Using a parameterized class
import { ModalClient } from "modal";
const modal = new ModalClient();
// Reference the deployed class
const modelCls = await modal.cls.fromName("my-app", "LLM");
// Create an instance with specific parameters
const instance = await modelCls.instance({
model_name: "gpt-4",
temperature: 0.8,
max_tokens: 1000,
});
// Call a method on the instance
const generateMethod = instance.method("generate");
const response = await generateMethod.remote([
"Explain quantum computing"
]);
console.log(response);
Example: Override runtime configuration
import { ModalClient } from "modal";
const modal = new ModalClient();
const cls = await modal.cls.fromName("my-app", "Trainer");
// Use more powerful hardware for training
const clsWithGpu = cls.withOptions({
gpu: "A100:4",
memoryMiB: 32768,
timeoutMs: 3600000, // 1 hour
});
const instance = await clsWithGpu.instance();
const trainMethod = instance.method("train");
await trainMethod.remote(["dataset.csv"]);