Modal JavaScript SDK

https://modal-labs.github.io/libmodal
Admin
The Modal JavaScript SDK provides convenient, on-demand access to serverless cloud compute on Modal...
Tokens:26,611
Snippets:183
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Modal JavaScript SDK with npm

Source: https://modal-labs.github.io/libmodal/index

This command installs the Modal JavaScript SDK package using npm. Ensure you have Node.js version 22 or later installed. This package provides both ES Modules and CommonJS formats.

```bash
npm install modal
```

--------------------------------

### Instantiate ModalClient and Get Function by Name (JavaScript)

Source: https://modal-labs.github.io/libmodal/classes/FunctionService

Demonstrates how to instantiate the ModalClient and retrieve a function by its application and function name. This is the standard way to interact with functions through the client.

```javascript
const modal = new ModalClient();
const function = await modal.functions.fromName("my-app", "my-function");
```

--------------------------------

### Authenticate with Modal using Environment Variables

Source: https://modal-labs.github.io/libmodal/index

Sets environment variables for authentication with Modal in machine environments. Replace the placeholder values with your actual Modal token ID and secret. This is an alternative to using the `modal setup` CLI command.

```bash
# Replace these with your actual token!
export MODAL_TOKEN_ID=ak-NOTAREALTOKENSTRINGXYZ
export MODAL_TOKEN_SECRET=as-FAKESECRETSTRINGABCDEF
```

--------------------------------

### Image Class - Overview

Source: https://modal-labs.github.io/libmodal/classes/Image

The Image class is a container image used for starting Sandboxes in Modal. It provides accessors and methods for image management.

```APIDOC
## Class Image
A container image, used for starting Sandboxes.

### Accessors
- `imageId` (string): Returns the image ID.

### Methods
- `build(app: App)`: Eagerly builds an Image on Modal.
- `dockerfileCommands(commands: string[], params?: ImageDockerfileCommandsParams)`: Extends an image with arbitrary Dockerfile-like commands.
- `delete(imageId: string, _?: ImageDeleteParams)`: Deletes an image. (Deprecated: Use `client.images.delete()` instead.)
- `fromAwsEcr(tag: string, secret: Secret)`: Creates an Image from AWS ECR. (Deprecated: Use `client.images.fromAwsEcr()` instead.)
- `fromGcpArtifactRegistry(tag: string, secret: Secret)`: Creates an Image from Google Cloud Artifact Registry. (Deprecated: Use `client.images.fromGcpArtifactRegistry()` instead.)
- `fromId(imageId: string)`: Retrieves an Image by its ID. (Deprecated: Use `client.images.fromId()` instead.)
- `fromRegistry(tag: string, secret?: Secret)`: Creates an Image from a container registry. (Deprecated: Use `client.images.fromRegistry()` instead.)
```

--------------------------------

### Create Sandbox Instance with ModalClient

Source: https://modal-labs.github.io/libmodal/classes/SandboxService

Demonstrates how to instantiate a ModalClient and then create a new sandbox using the client. This is the typical entry point for interacting with sandboxes.

```javascript
const modal = new ModalClient();
const sandbox = await modal.sandboxes.create(app, image);
```

--------------------------------

### GET /images/{imageId}

Source: https://modal-labs.github.io/libmodal/classes/ImageService

Retrieves an Image by its ID.

```APIDOC
## GET /images/{imageId}

### Description
Creates an Image from an Image ID.

### Method
GET

### Endpoint
/images/{imageId}

### Parameters
#### Path Parameters
- **imageId** (string) - Required - The ID of the image to retrieve.

### Response
#### Success Response (200)
- **image_details** (object) - Details of the retrieved image.
  - **id** (string) - The image ID.
  - **tag** (string) - The image tag.

#### Response Example
```json
{
  "image_details": {
    "id": "img_abc123def456",
    "tag": "alpine:latest"
  }
}
```
```

--------------------------------

### Instantiate ImageService and Create Image from Registry

Source: https://modal-labs.github.io/libmodal/classes/ImageService

Demonstrates how to instantiate a ModalClient and use the ImageService to fetch an image from a registry. This is the primary way users interact with image management.

```javascript
const modal = new ModalClient();  
const image = await modal.images.fromRegistry("alpine");
```

--------------------------------

### Initialize ProxyService with ModalClient

Source: https://modal-labs.github.io/libmodal/classes/ProxyService

Demonstrates how to instantiate the ProxyService by passing a ModalClient instance. This is the primary way to set up the service for managing proxies.

```typescript
const modalClient = new ModalClient();
const proxyService = new ProxyService(modalClient);
```

--------------------------------

### ImageService Constructor

Source: https://modal-labs.github.io/libmodal/classes/ImageService

Initializes a new instance of the ImageService class.

```APIDOC
## ImageService Constructor

### Description
Initializes a new instance of the ImageService class.

### Method
constructor

### Parameters
- **client** (ModalClient) - Required - The Modal client instance.

### Returns
- ImageService

### Request Example
```json
{
  "client": "<ModalClient_instance>"
}
```

### Response Example
```json
{
  "instance": "<ImageService_instance>"
}
```
```

--------------------------------

### Getting Sandbox Tags

Source: https://modal-labs.github.io/libmodal/classes/Sandbox

Retrieves the key-value tags associated with a specific sandbox instance from the server. This is useful for identifying or filtering sandboxes based on custom metadata.

```typescript
import modal

# Assuming 'sandbox' is an instance of modal.Sandbox

async def get_sandbox_tags(sandbox):
    tags = await sandbox.getTags()
    print(tags)

```

--------------------------------

### ModalClient Constructor

Source: https://modal-labs.github.io/libmodal/classes/ModalClient

Initializes a new instance of the ModalClient. Optionally accepts ModalClientParams for configuration.

```APIDOC
## new ModalClient

### Description
Initializes a new instance of the ModalClient class.

### Method
constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `params` (ModalClientParams) - Optional - Configuration parameters for the client.

### Request Example
```json
{
  "params": { /* ModalClientParams object */ }
}
```

### Response
#### Success Response (200)
* `ModalClient` - An instance of the ModalClient.

#### Response Example
```json
{
  "clientInstance": "{...}" 
}
```
```

--------------------------------

### Getting Sandbox Tunnels

Source: https://modal-labs.github.io/libmodal/classes/Sandbox

Retrieves metadata about active tunnels for the sandbox. Tunnels map container ports to host ports, enabling external access to services running inside the sandbox. A timeout is available for tunnel availability.

```typescript
import modal

# Assuming 'sandbox' is an instance of modal.Sandbox

async def get_sandbox_tunnels(sandbox):
    try:
        tunnels = await sandbox.tunnels(timeoutMs=10000) # 10 seconds timeout
        print(tunnels)
    except modal.SandboxTimeoutError as e:
        print(f"Tunnels not available: {e}")

```

--------------------------------

### Initialize ModalClient and Access Queue

Source: https://modal-labs.github.io/libmodal/classes/QueueService

Demonstrates how to initialize a ModalClient and access a queue by its name. This is the standard way to interact with queues using the Modal client library.

```javascript
const modal = new ModalClient();
const queue = await modal.queues.fromName("my-queue");
```

--------------------------------

### AppService Constructor

Source: https://modal-labs.github.io/libmodal/classes/AppService

Initializes a new instance of the AppService class, which manages Modal applications.

```APIDOC
## AppService Constructor

### Description
Initializes a new instance of the AppService class.

### Method
Constructor

### Parameters
- **client** (ModalClient) - Required - The Modal client instance.

### Returns
- AppService - A new instance of the AppService.
```

--------------------------------

### Instantiate CloudBucketMount

Source: https://modal-labs.github.io/libmodal/classes/CloudBucketMount

Demonstrates how to create an instance of the CloudBucketMount class. This involves providing the bucket name and optional parameters for configuration, such as endpoint URL, key prefix, IAM role, and read-only access.

```typescript
import { Secret, CloudBucketMount } from '@modal/labs';

// Example instantiation with minimal parameters
const myBucketMount = new CloudBucketMount('my-bucket-name');

// Example instantiation with all optional parameters
const myDetailedBucketMount = new CloudBucketMount('another-bucket-name', {
  bucketEndpointUrl: 'https://s3.amazonaws.com',
  keyPrefix: 'data/',
  oidcAuthRoleArn: 'arn:aws:iam::123456789012:role/my-role',
  readOnly: true,
  requesterPays: false,
  secret: new Secret({
    env_vars: {
      AWS_ACCESS_KEY_ID: 'YOUR_ACCESS_KEY',
      AWS_SECRET_ACCESS_KEY: 'YOUR_SECRET_KEY'
    }
  })
});
```

--------------------------------

### Instantiate and Use AppService (JavaScript)

Source: https://modal-labs.github.io/libmodal/classes/AppService

Demonstrates how to instantiate a ModalClient and access the AppService to retrieve an application by its name. This is the standard way to interact with deployed applications.

```javascript
const modal = new ModalClient();
const app = await modal.apps.fromName("my-app");
```

--------------------------------

### ContainerProcess Constructor

Source: https://modal-labs.github.io/libmodal/classes/ContainerProcess

Information on how to instantiate a ContainerProcess object.

```APIDOC
## Constructors
### constructor
  * new ContainerProcess<R extends string | Uint8Array<ArrayBufferLike> = any>(
client: ModalClient,
execId: string,
params?: SandboxExecParams,
): ContainerProcess<R>
#### Type Parameters
    * R extends string | Uint8Array<ArrayBufferLike> = any
#### Parameters
    * client: ModalClient
    * execId: string
    * `Optional`params: SandboxExecParams
#### Returns ContainerProcess<R>
```

--------------------------------

### Sandbox Class Methods

Source: https://modal-labs.github.io/libmodal/classes/Sandbox

Provides documentation for the methods available on the Sandbox class, including execution, file operations, and state management.

```APIDOC
## POST /sandbox/exec

### Description
Executes a command within the sandbox. Supports both text and binary modes.

### Method
POST

### Endpoint
/sandbox/exec

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **command** (string[]) - Required - The command and its arguments to execute.
- **params** (SandboxExecParams & { mode?: "text" | "binary" }) - Optional - Execution parameters, including the mode.

### Request Example
```json
{
  "command": ["ls", "-l"],
  "params": {"mode": "text"}
}
```

### Response
#### Success Response (200)
- **stdout** (ModalReadStream<string> | ModalReadStream<Uint8Array<ArrayBufferLike>>) - The standard output of the executed command.
- **stderr** (ModalReadStream<string>) - The standard error of the executed command.
- **stdin** (ModalWriteStream<string>) - The standard input stream for the executed command.

#### Response Example
```json
{
  "stdout": "<stream_handle>",
  "stderr": "<stream_handle>",
  "stdin": "<stream_handle>"
}
```
```

```APIDOC
## GET /sandbox/tags

### Description
Retrieves the tags associated with the sandbox.

### Method
GET

### Endpoint
/sandbox/tags

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **tags** (Record<string, string>) - A key-value map of tags.

#### Response Example
```json
{
  "tags": {
    "environment": "production",
    "owner": "dev-team"
  }
}
```
```

```APIDOC
## POST /sandbox/open

### Description
Opens a file in the sandbox filesystem.

### Method
POST

### Endpoint
/sandbox/open

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **path** (string) - Required - The path to the file.
- **mode** (SandboxFileMode) - Optional - The file open mode (e.g., 'r', 'w', 'a'). Defaults to 'r'.

### Request Example
```json
{
  "path": "/app/data.txt",
  "mode": "w"
}
```

### Response
#### Success Response (200)
- **fileHandle** (SandboxFile) - A handle to the opened file.

#### Response Example
```json
{
  "fileHandle": "<file_handle>"
}
```
```

```APIDOC
## GET /sandbox/poll

### Description
Checks if the sandbox has finished running.

### Method
GET

### Endpoint
/sandbox/poll

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **exitCode** (number | null) - The exit code if the sandbox has finished, or null if it's still running.

#### Response Example
```json
{
  "exitCode": 0
}
```
```

```APIDOC
## POST /sandbox/setTags

### Description
Sets tags on the sandbox.

### Method
POST

### Endpoint
/sandbox/setTags

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tags** (Record<string, string>) - Required - The tags to set.

### Request Example
```json
{
  "tags": {
    "status": "active"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

```APIDOC
## POST /sandbox/snapshotFilesystem

### Description
Snapshots the sandbox's filesystem.

### Method
POST

### Endpoint
/sandbox/snapshotFilesystem

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **timeoutMs** (number) - Optional - Timeout for the snapshot operation in milliseconds. Defaults to 55000.

### Request Example
```json
{
  "timeoutMs": 60000
}
```

### Response
#### Success Response (200)
- **image** (Image) - An Image object representing the snapshot.

#### Response Example
```json
{
  "image": {
    "id": "img-abc123"
  }
}
```
```

```APIDOC
## POST /sandbox/terminate

### Description
Terminates the sandbox.

### Method
POST

### Endpoint
/sandbox/terminate

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "terminated"
}
```
```

```APIDOC
## GET /sandbox/tunnels

### Description
Retrieves tunnel metadata for the sandbox.

### Method
GET

### Endpoint
/sandbox/tunnels

### Parameters
#### Path Parameters
None

#### Query Parameters
- **timeoutMs** (number) - Optional - Timeout for tunnel availability in milliseconds. Defaults to 50000.

### Request Example
```json
{
  "timeoutMs": 60000
}
```

### Response
#### Success Response (200)
- **tunnels** (Record<number, Tunnel>) - A dictionary of tunnel objects keyed by container port.

#### Response Example
```json
{
  "tunnels": {
    "8080": {"port": 8080, "local_port": 3000}
  }
}
```
```

```APIDOC
## POST /sandbox/wait

### Description
Waits for the sandbox to finish execution.

### Method
POST

### Endpoint
/sandbox/wait

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **exitCode** (number) - The exit code of the sandbox.

#### Response Example
```json
{
  "exitCode": 0
}
```
```

--------------------------------

### Modal Cls - Instance Creation

Source: https://modal-labs.github.io/libmodal/classes/Cls

Create a new instance of the Cls with specified parameters and optional runtime configurations.

```APIDOC
## POST /modal/cls/instance

### Description
Create a new instance of the Cls with parameters and/or runtime options.

### Method
POST

### Endpoint
/modal/cls/instance

### Parameters
#### Request Body
- **parameters** (Record<string, any>) - Optional - Parameters for the Cls instance.

### Request Example
```json
{
  "parameters": {
    "key1": "value1",
    "key2": 123
  }
}
```

### Response
#### Success Response (200)
- **ClsInstance** (object) - An object representing the deployed Cls instance.

#### Response Example
```json
{
  "instanceId": "cls-12345",
  "status": "running"
}
```
```

--------------------------------

### FunctionService Constructor

Source: https://modal-labs.github.io/libmodal/classes/FunctionService

Initializes a new instance of the FunctionService class.

```APIDOC
## Constructor FunctionService

### Description
Initializes a new instance of the FunctionService class.

### Method
Constructor

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const modal = new ModalClient();
const functionService = new FunctionService(modal);
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Instantiate and Use VolumeService with ModalClient (JavaScript)

Source: https://modal-labs.github.io/libmodal/classes/VolumeService

Demonstrates how to create a ModalClient instance and access the VolumeService to retrieve a Volume by its name. This is the standard way to interact with volumes in the Modal client library.

```javascript
const modal = new ModalClient();
const volume = await modal.volumes.fromName("my-volume");
```

--------------------------------

### Initialize and Use ModalClient in TypeScript

Source: https://modal-labs.github.io/libmodal/classes/ModalClient

Demonstrates how to create an instance of ModalClient and use its properties to interact with Modal services like apps, images, and sandboxes. This requires the 'modal' package.

```typescript
import { ModalClient } from "modal";  
  
const modal = new ModalClient();  
  
const app = await modal.apps.fromName("my-app");  
const image = modal.images.fromRegistry("python:3.13");  
const sandbox = await modal.sandboxes.create(app, image);
```

--------------------------------

### SandboxFile Methods

Source: https://modal-labs.github.io/libmodal/classes/SandboxFile

Operations for managing and interacting with an open file in the Sandbox filesystem.

```APIDOC
## SandboxFile Class

SandboxFile represents an open file in the Sandbox filesystem. Provides read/write operations similar to Node.js `fsPromises.FileHandle`.

### Methods

#### `close()`

*   **Description**: Close the file handle.
*   **Method**: Promise<void>
*   **Returns**: Promise<void>

#### `flush()`

*   **Description**: Flush any buffered data to the file.
*   **Method**: Promise<void>
*   **Returns**: Promise<void>

#### `read()`

*   **Description**: Read data from the file.
*   **Method**: Promise<Uint8Array>
*   **Returns**: Promise<Uint8Array> - Promise that resolves to the read data as Uint8Array.

#### `write(data: Uint8Array)`

*   **Description**: Write data to the file.
*   **Method**: Promise<void>
*   **Parameters**:
    *   `data` (Uint8Array) - Required - Data to write (string or Uint8Array).
*   **Returns**: Promise<void>
```

--------------------------------

### SandboxFile Class Methods

Source: https://modal-labs.github.io/libmodal/classes/SandboxFile

This snippet outlines the core methods available on the SandboxFile class: close, flush, read, and write. These methods facilitate basic file I/O operations within the sandbox.

```typescript
class SandboxFile {
  // ...
  close(): Promise<void>;
  flush(): Promise<void>;
  read(): Promise<Uint8Array>;
  write(data: Uint8Array): Promise<void>;
  // ...
}
```

--------------------------------

### Create QueueService Instance

Source: https://modal-labs.github.io/libmodal/classes/QueueService

Illustrates the constructor for the QueueService class, which requires a ModalClient instance. This is used internally by the Modal client to manage queue operations.

```javascript
const queueService = new QueueService(client);
```

--------------------------------

### Instantiate FunctionCallService with ModalClient

Source: https://modal-labs.github.io/libmodal/classes/FunctionCallService

Demonstrates how to create an instance of FunctionCallService by passing a ModalClient object to its constructor. This is the standard way to initialize the service for managing function calls.

```typescript
import { ModalClient, FunctionCallService } from 'modal-client';

const client = new ModalClient();
const functionCallService = new FunctionCallService(client);
```

--------------------------------

### Image.dockerfileCommands()

Source: https://modal-labs.github.io/libmodal/classes/Image

Extends an image with arbitrary Dockerfile-like commands. Each call creates a new Image layer that will be built sequentially.

```APIDOC
## POST /dockerfileCommands

### Description
Extend an image with arbitrary Dockerfile-like commands. Each call creates a new Image layer that will be built sequentially.

### Method
POST

### Endpoint
/dockerfileCommands

### Parameters
#### Request Body
- **commands** (string[]) - Required - Array of Dockerfile commands as strings.
- **params** (ImageDockerfileCommandsParams) - Optional - Optional configuration for this layer's build.

### Request Example
```json
{
  "commands": [
    "RUN apt-get update && apt-get install -y python3",
    "COPY . /app"
  ],
  "params": {
    "image_tag": "latest"
  }
}
```

### Response
#### Success Response (200)
- **image** (Image) - A new Image instance representing the extended image.

#### Response Example
```json
{
  "image": {
    "imageId": "img-abcdef789012"
  }
}
```
```

--------------------------------

### App Class Methods

Source: https://modal-labs.github.io/libmodal/classes/App

Methods for the Modal App class, including creating sandboxes and importing images. Note that many of these methods are deprecated.

```APIDOC
## POST /apps/{appId}/sandboxes

### Description
Creates a new sandbox environment for a Modal App. This method is deprecated and client.sandboxes.create() should be used instead.

### Method
POST

### Endpoint
/apps/{appId}/sandboxes

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app to create a sandbox for.

#### Request Body
- **image** (Image) - Required - The container image to use for the sandbox.
- **options** (SandboxCreateParams) - Optional - Additional parameters for sandbox creation.

### Request Example
```json
{
  "image": { /* Image object */ },
  "options": { /* SandboxCreateParams object */ }
}
```

### Response
#### Success Response (200)
- **sandbox** (Sandbox) - The created sandbox object.

#### Response Example
```json
{
  "sandbox": { /* Sandbox object */ }
}
```

## POST /apps/{appId}/images/aws-ecr

### Description
Imports a container image from AWS ECR. This method is deprecated and client.images.fromAwsEcr() should be used instead.

### Method
POST

### Endpoint
/apps/{appId}/images/aws-ecr

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app associated with the image.

#### Request Body
- **tag** (string) - Required - The tag of the image in ECR.
- **secret** (Secret) - Required - The secret containing AWS credentials.

### Request Example
```json
{
  "tag": "latest",
  "secret": { /* Secret object */ }
}
```

### Response
#### Success Response (200)
- **image** (Image) - The imported Image object.

#### Response Example
```json
{
  "image": { /* Image object */ }
}
```

## POST /apps/{appId}/images/gcp-artifact-registry

### Description
Imports a container image from Google Cloud Artifact Registry. This method is deprecated and client.images.fromGcpArtifactRegistry() should be used instead.

### Method
POST

### Endpoint
/apps/{appId}/images/gcp-artifact-registry

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app associated with the image.

#### Request Body
- **tag** (string) - Required - The tag of the image in the artifact registry.
- **secret** (Secret) - Required - The secret containing GCP credentials.

### Request Example
```json
{
  "tag": "v1.0",
  "secret": { /* Secret object */ }
}
```

### Response
#### Success Response (200)
- **image** (Image) - The imported Image object.

#### Response Example
```json
{
  "image": { /* Image object */ }
}
```

## POST /apps/{appId}/images/registry

### Description
Imports a container image from a generic registry. This method is deprecated and client.images.fromRegistry() should be used instead.

### Method
POST

### Endpoint
/apps/{appId}/images/registry

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app associated with the image.

#### Request Body
- **tag** (string) - Required - The tag of the image in the registry.
- **secret** (Secret) - Optional - The secret containing registry credentials.

### Request Example
```json
{
  "tag": "latest",
  "secret": { /* Secret object */ }
}
```

### Response
#### Success Response (200)
- **image** (Image) - The imported Image object.

#### Response Example
```json
{
  "image": { /* Image object */ }
}
```

## GET /apps/lookup

### Description
Looks up an App by its name. This method is deprecated and client.apps.fromName() should be used instead.

### Method
GET

### Endpoint
/apps/lookup

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the app to look up.
- **options** (LookupOptions) - Optional - Additional options for the lookup.

### Request Example
```json
{
  "name": "my-app",
  "options": { /* LookupOptions object */ }
}
```

### Response
#### Success Response (200)
- **app** (App) - The found App object.

#### Response Example
```json
{
  "app": { /* App object */ }
}
```
```

--------------------------------

### POST /images/fromGcpArtifactRegistry

Source: https://modal-labs.github.io/libmodal/classes/ImageService

Creates an Image from a raw GCP Artifact Registry tag.

```APIDOC
## POST /images/fromGcpArtifactRegistry

### Description
Creates an Image from a raw registry tag, optionally using a Secret for authentication.

### Method
POST

### Endpoint
/images/fromGcpArtifactRegistry

### Parameters
#### Request Body
- **tag** (string) - Required - The registry tag for the Image.
- **secret** (Secret) - Required - A Secret containing credentials for registry authentication.

### Request Example
```json
{
  "tag": "us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest",
  "secret": {
    "type": "gcp",
    "token": "YOUR_GCP_TOKEN"
  }
}
```

### Response
#### Success Response (200)
- **image_id** (string) - The ID of the created Image.

#### Response Example
```json
{
  "image_id": "img_abc123def456"
}
```
```

--------------------------------

### Function Class Documentation

Source: https://modal-labs.github.io/libmodal/classes/Function_

Details about the Function class, its properties, and methods for interacting with deployed functions.

```APIDOC
## Function Class

Represents a deployed Modal Function, which can be invoked remotely.

### Properties
* **`functionId`** (string) - The unique identifier for the function.
* **`methodName`** (string, optional) - The name of the method to invoke.

### Methods

#### `getCurrentStats()`
Retrieves the current statistics for the function.

* **Returns:** `Promise<FunctionStats>`

#### `getWebUrl()`
Gets the URL of the function if it's running as a web endpoint.

* **Returns:** `Promise<undefined | string>` - The web URL or undefined.

#### `remote(args?, kwargs?)`
Invokes the function remotely.

* **Parameters:**
  * `args` (any[], optional) - Positional arguments for the function.
  * `kwargs` (Record<string, any>, optional) - Keyword arguments for the function.
* **Returns:** `Promise<any>`

#### `spawn(args?, kwargs?)`
Spawns a new instance of the function.

* **Parameters:**
  * `args` (any[], optional) - Positional arguments for the function.
  * `kwargs` (Record<string, any>, optional) - Keyword arguments for the function.
* **Returns:** `Promise<FunctionCall>`

#### `updateAutoscaler(params)`
Updates the autoscaling configuration for the function.

* **Parameters:**
  * `params` (FunctionUpdateAutoscalerParams) - The autoscaling parameters.
* **Returns:** `Promise<void>`

#### `lookup(appName, name, params?)`
(Static Method) Looks up a function by its application name and function name.

* **Parameters:**
  * `appName` (string) - The name of the application.
  * `name` (string) - The name of the function.
  * `params` (FunctionFromNameParams, optional) - Additional parameters for lookup.
* **Returns:** `Promise<Function_>`
* **Deprecated:** Use `client.functions.fromName()` instead.
```

--------------------------------

### Sandbox Static Methods (Deprecated)

Source: https://modal-labs.github.io/libmodal/classes/Sandbox

Documentation for static methods to create and list sandboxes. These are deprecated in favor of client.sandboxes.

```APIDOC
## GET /sandboxes/fromId

### Description
Retrieves a sandbox by its ID. Deprecated.

### Method
GET

### Endpoint
/sandboxes/fromId

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sandboxId** (string) - Required - The ID of the sandbox.

### Request Example
```json
{
  "sandboxId": "sbx-12345"
}
```

### Response
#### Success Response (200)
- **sandbox** (Sandbox) - The Sandbox object.

#### Response Example
```json
{
  "sandbox": {
    "sandboxId": "sbx-12345"
  }
}
```
```

```APIDOC
## GET /sandboxes/fromName

### Description
Retrieves a sandbox by its application name and sandbox name. Deprecated.

### Method
GET

### Endpoint
/sandboxes/fromName

### Parameters
#### Path Parameters
None

#### Query Parameters
- **appName** (string) - Required - The name of the application.
- **name** (string) - Required - The name of the sandbox.
- **environment** (string) - Optional - The environment name.

### Request Example
```json
{
  "appName": "my-app",
  "name": "worker-sandbox",
  "environment": "dev"
}
```

### Response
#### Success Response (200)
- **sandbox** (Sandbox) - The Sandbox object.

#### Response Example
```json
{
  "sandbox": {
    "sandboxId": "sbx-67890",
    "appName": "my-app",
    "name": "worker-sandbox"
  }
}
```
```

```APIDOC
## GET /sandboxes/list

### Description
Lists sandboxes. Deprecated.

### Method
GET

### Endpoint
/sandboxes/list

### Parameters
#### Path Parameters
None

#### Query Parameters
- **params** (SandboxListParams) - Optional - Parameters for filtering the list.

### Request Example
```json
{
  "params": {
    "tag_filters": {"owner": "dev-team"}
  }
}
```

### Response
#### Success Response (200)
- **sandboxes** (AsyncGenerator<Sandbox, void, unknown>) - An asynchronous generator yielding Sandbox objects.

#### Response Example
```json
{
  "sandboxes": "<generator_handle>"
}
```
```

--------------------------------

### Snapshotting Sandbox Filesystem

Source: https://modal-labs.github.io/libmodal/classes/Sandbox

Creates an image snapshot of the sandbox's current filesystem state. This image can later be used to spawn new sandboxes with the same filesystem content. A timeout can be specified for the operation.

```typescript
import modal

# Assuming 'sandbox' is an instance of modal.Sandbox

async def snapshot_sandbox(sandbox):
    image = await sandbox.snapshotFilesystem(timeoutMs=60000) # 60 seconds timeout
    print("Filesystem snapshot created.")
    # 'image' can be used to create new sandboxes

```

--------------------------------

### QueueService Class

Source: https://modal-labs.github.io/libmodal/classes/QueueService

Documentation for the QueueService class, which manages queues within the Modal client.

```APIDOC
## Class QueueService

Service for managing Queues. Normally only ever accessed via the client as:
```javascript
const modal = new ModalClient();
const queue = await modal.queues.fromName("my-queue");
```

### Constructor

## Constructor
### new QueueService(client: ModalClient)

Initializes a new instance of the QueueService.

#### Parameters

*   **client** (ModalClient) - The Modal client instance.

#### Returns

*   QueueService - A new instance of the QueueService.

### Methods

## Methods

### delete

## delete
  * delete(name: string, params?: QueueDeleteParams): Promise<void>

Delete a Queue by name.

#### Parameters

*   **name** (string) - The name of the queue to delete.
*   **params** (QueueDeleteParams) - Optional parameters for deletion. Defaults to {}.

#### Returns

*   Promise<void> - A promise that resolves when the queue is deleted.

### ephemeral

## ephemeral
  * ephemeral(params?: QueueEphemeralParams): Promise<Queue>

Create a nameless, temporary Queue. You will need to call Queue.closeEphemeral() to delete the Queue.

#### Parameters

*   **params** (QueueEphemeralParams) - Optional parameters for creating an ephemeral queue. Defaults to {}.

#### Returns

*   Promise<Queue> - A promise that resolves with the created ephemeral Queue object.

### fromName

## fromName
  * fromName(name: string, params?: QueueFromNameParams): Promise<Queue>

Reference a Queue by name.

#### Parameters

*   **name** (string) - The name of the queue to reference.
*   **params** (QueueFromNameParams) - Optional parameters for referencing the queue. Defaults to {}.

#### Returns

*   Promise<Queue> - A promise that resolves with the referenced Queue object.

```

--------------------------------

### Image.build()

Source: https://modal-labs.github.io/libmodal/classes/Image

Eagerly builds an Image on Modal. This method initiates the image build process on Modal.

```APIDOC
## POST /build

### Description
Eagerly builds an Image on Modal.

### Method
POST

### Endpoint
/build

### Parameters
#### Request Body
- **app** (App) - Required - The App object to use for building the Image.

### Request Example
```json
{
  "app": "your_app_object"
}
```

### Response
#### Success Response (200)
- **image** (Image) - The built Image object.

#### Response Example
```json
{
  "image": {
    "imageId": "img-abcdef123456"
  }
}
```
```

--------------------------------

### Instantiate ClsService and Reference Cls via Client (JavaScript)

Source: https://modal-labs.github.io/libmodal/classes/ClsService

Demonstrates how to create a ModalClient instance, access the ClsService through it, and then reference a specific Cls by its application and name. This is the standard way to interact with Cls objects from a client application.

```javascript
const modal = new ModalClient();
const cls = await modal.cls.fromName("my-app", "MyCls");
```

--------------------------------

### SecretService Constructor

Source: https://modal-labs.github.io/libmodal/classes/SecretService

Initializes a new instance of the SecretService class.

```APIDOC
## new SecretService(client: ModalClient)

### Description
Initializes a new instance of the SecretService class.

### Method
constructor

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```javascript
const modal = new ModalClient();
const secretService = new SecretService(modal);
```

### Response
#### Success Response (200)
- None

#### Response Example
```json
{}
```
```

--------------------------------

### Queue Class Methods

Source: https://modal-labs.github.io/libmodal/classes/Queue

This section details the methods available on a Queue instance for interacting with the queue's data and state.

```APIDOC
## Queue Methods

### clear

Remove all objects from a Queue partition.

### Method

```
clear(params?: QueueClearParams): Promise<void>
```

### Description

Removes all items from a specific partition of the queue.

### Parameters

#### Query Parameters

- **params** (QueueClearParams) - Optional - Parameters for clearing the queue partition.

### Response

#### Success Response (200)

- **void** - Indicates the operation was successful.

### clear (ephemeral)

Delete the ephemeral Queue. Only usable with ephemeral Queues.

### Method

```
closeEphemeral(): void
```

### Description

Deletes an ephemeral queue. This method is only applicable to queues created as ephemeral.

### Response

#### Success Response (200)

- **void** - Indicates the operation was successful.

### get

Remove and return the next object from the Queue.
By default, this will wait until at least one item is present in the Queue. If `timeoutMs` is set, raises `QueueEmptyError` if no items are available within that timeout in milliseconds.

### Method

```
get(params?: QueueGetParams): Promise<any>
```

### Description

Retrieves and removes the next item from the queue. It can optionally wait for an item or time out.

### Parameters

#### Query Parameters

- **params** (QueueGetParams) - Optional - Parameters for retrieving an item, including timeout settings.

### Response

#### Success Response (200)

- **any** - The retrieved object from the queue.

### getMany

Remove and return up to `n` objects from the Queue.
By default, this will wait until at least one item is present in the Queue. If `timeoutMs` is set, raises `QueueEmptyError` if no items are available within that timeout in milliseconds.

### Method

```
getMany(n: number, params?: QueueGetParams): Promise<any[]>
```

### Description

Retrieves and removes up to a specified number of items from the queue, with optional waiting or timeout.

### Parameters

#### Path Parameters

- **n** (number) - Required - The maximum number of items to retrieve.

#### Query Parameters

- **params** (QueueGetParams) - Optional - Parameters for retrieving items, including timeout settings.

### Response

#### Success Response (200)

- **any[]** - An array of retrieved objects from the queue.

### iterate

Iterate through items in a Queue without mutation.

### Method

```
iterate(params?: QueueIterateParams): AsyncGenerator<any, void, unknown>
```

### Description

Provides an asynchronous iterator to go through items in the queue without removing them.

### Parameters

#### Query Parameters

- **params** (QueueIterateParams) - Optional - Parameters for the iteration.

### Response

#### Success Response (200)

- **AsyncGenerator** - An async generator yielding items from the queue.

### len

Return the number of objects in the Queue.

### Method

```
len(params?: QueueLenParams): Promise<number>
```

### Description

Returns the current count of items in the queue.

### Parameters

#### Query Parameters

- **params** (QueueLenParams) - Optional - Parameters for getting the queue length.

### Response

#### Success Response (200)

- **number** - The number of items currently in the queue.

### put

Add an item to the end of the Queue.
If the Queue is full, this will retry with exponential backoff until the provided `timeoutMs` is reached, or indefinitely if `timeoutMs` is not set. Raises QueueFullError if the Queue is still full after the timeout.

### Method

```
put(v: any, params?: QueuePutParams): Promise<void>
```

### Description

Adds a single item to the end of the queue. Handles retries if the queue is full within a specified timeout.

### Parameters

#### Path Parameters

- **v** (any) - Required - The item to add to the queue.

#### Query Parameters

- **params** (QueuePutParams) - Optional - Parameters for putting the item, including timeout settings.

### Response

#### Success Response (200)

- **void** - Indicates the operation was successful.

### putMany

Add several items to the end of the Queue.
If the Queue is full, this will retry with exponential backoff until the provided `timeoutMs` is reached, or indefinitely if `timeoutMs` is not set. Raises QueueFullError if the Queue is still full after the timeout.

### Method

```
putMany(values: any[], params?: QueuePutParams): Promise<void>
```

### Description

Adds multiple items to the end of the queue. Similar to `put`, it handles retries for full queues.

### Parameters

#### Path Parameters

- **values** (any[]) - Required - An array of items to add to the queue.

#### Query Parameters

- **params** (QueuePutParams) - Optional - Parameters for putting the items, including timeout settings.

### Response

#### Success Response (200)

- **void** - Indicates the operation was successful.
```

--------------------------------

### ContainerProcess Class

Source: https://modal-labs.github.io/libmodal/classes/ContainerProcess

Details about the ContainerProcess class, its constructors, properties, and methods.

```APIDOC
## Class ContainerProcess<R>

#### Type Parameters
  * R extends string | Uint8Array = any

##### Index
### Constructors
constructor
### Properties
returncode stderr stdin stdout
### Methods
wait
```

--------------------------------

### ModalClient Methods

Source: https://modal-labs.github.io/libmodal/classes/ModalClient

Methods available on the ModalClient instance for performing actions and retrieving information.

```APIDOC
## ModalClient Methods

### Description
Provides methods for interacting with Modal services and retrieving client information.

### Methods
#### close
  * `close(): void`
  * **Description**: Closes the connection to Modal services.
  * **Returns**: void

#### environmentName
  * `environmentName(environment?: string): string`
  * **Description**: Gets or sets the current environment name.
  * **Parameters**:
    * `environment` (string) - Optional - The environment name to set.
  * **Returns**: string - The current environment name.

#### imageBuilderVersion
  * `imageBuilderVersion(version?: string): string`
  * **Description**: Gets or sets the image builder version.
  * **Parameters**:
    * `version` (string) - Optional - The image builder version to set.
  * **Returns**: string - The current image builder version.

#### version
  * `version(): string`
  * **Description**: Gets the version of the Modal client library.
  * **Returns**: string - The client library version.

### Example
```javascript
const modal = new ModalClient();
modal.close();
const env = modal.environmentName();
const version = modal.version();
```
```

--------------------------------

### POST /images/fromRegistry

Source: https://modal-labs.github.io/libmodal/classes/ImageService

Creates an Image from a raw registry tag.

```APIDOC
## POST /images/fromRegistry

### Description
Creates an Image from a raw registry tag, optionally using a Secret for authentication.

### Method
POST

### Endpoint
/images/fromRegistry

### Parameters
#### Request Body
- **tag** (string) - Required - The registry tag for the Image.
- **secret** (Secret) - Optional - A Secret containing credentials for registry authentication.

### Request Example
```json
{
  "tag": "ubuntu:22.04",
  "secret": {
    "type": "dockerhub",
    "username": "myuser",
    "password": "mypassword"
  }
}
```

### Response
#### Success Response (200)
- **image_id** (string) - The ID of the created Image.

#### Response Example
```json
{
  "image_id": "img_xyz789uvw012"
}
```
```

--------------------------------

### CloudBucketMount Class

Source: https://modal-labs.github.io/libmodal/classes/CloudBucketMount

Details about the CloudBucketMount class, its constructor, and properties for accessing cloud storage buckets.

```APIDOC
## Class CloudBucketMount

Cloud Bucket Mounts provide access to cloud storage buckets within Modal Functions.

### Constructor

```typescript
new CloudBucketMount(
  bucketName: string,
  params?: {
    bucketEndpointUrl?: string;
    keyPrefix?: string;
    oidcAuthRoleArn?: string;
    readOnly?: boolean;
    requesterPays?: boolean;
    secret?: Secret;
  }
): CloudBucketMount
```

#### Parameters

*   **bucketName** (string) - The name of the bucket.
*   **params** (object) - Optional parameters for the bucket mount:
    *   **bucketEndpointUrl** (string) - Optional URL for the bucket endpoint.
    *   **keyPrefix** (string) - Optional prefix for keys within the bucket.
    *   **oidcAuthRoleArn** (string) - Optional ARN for OIDC authentication role.
    *   **readOnly** (boolean) - Whether the mount is read-only.
    *   **requesterPays** (boolean) - Whether the requester pays for access.
    *   **secret** (Secret) - Optional secret for authentication.

### Properties

*   **bucketName** (string) - The name of the bucket.
*   **bucketEndpointUrl** (string, optional) - The URL for the bucket endpoint.
*   **keyPrefix** (string, optional) - The prefix for keys within the bucket.
*   **oidcAuthRoleArn** (string, optional) - The ARN for OIDC authentication role.
*   **readOnly** (boolean) - Indicates if the mount is read-only.
*   **requesterPays** (boolean) - Indicates if the requester pays for access.
*   **secret** (Secret, optional) - The secret for authentication.
```

--------------------------------

### ContainerProcess Methods

Source: https://modal-labs.github.io/libmodal/classes/ContainerProcess

Information on the methods available for a ContainerProcess instance.

```APIDOC
## Methods
### wait
  * wait(): Promise<number>
Wait for process completion and return the exit code.
#### Returns Promise<number>
```
Tokens:
Raw