` | - | Environment variables |
| `blockNetwork` | `boolean` | - | Block network access |
| `name` | `string` | - | Sandbox name (unique within app) |
## GPU support
Modal supports NVIDIA GPUs for ML workloads:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
gpu: "T4", // or "L4", "A10G", "A100", "H100"
});
```
## Volumes and secrets
Mount Modal Volumes for persistent storage and inject secrets as environment variables:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Volumes and secrets must be created in Modal first
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
volumes: {
"/data": "my-data-volume",
"/models": "my-models-volume",
},
secrets: ["my-api-keys", "database-credentials"],
});
// Files in /data and /models persist across sandbox restarts
await sandbox.execute("echo 'Hello' > /data/test.txt");
// Secrets are available as environment variables
await sandbox.execute("echo $API_KEY");
```
## Initial files
Pre-populate the sandbox with files during creation:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
initialFiles: {
"/app/main.py": 'print("Hello from Python!")',
"/app/config.json": JSON.stringify({ name: "my-app" }, null, 2),
},
});
const result = await sandbox.execute("python /app/main.py");
```
## Accessing the Modal SDK
For advanced features not exposed by `BaseSandbox`, access the underlying Modal SDK:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const modalSandbox = await ModalSandbox.create();
const client = modalSandbox.client; // ModalClient
const instance = modalSandbox.instance; // Sandbox
// Direct SDK operations
const process = await instance.exec(["python", "-c", "print('Hello')"], {
stdout: "pipe",
stderr: "pipe",
});
```
## Reconnecting to existing sandboxes
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Reconnect by ID
const reconnected = await ModalSandbox.fromId(sandboxId);
// Reconnect by name
const reconnected2 = await ModalSandbox.fromName("my-app", "my-sandbox");
```
## Factory functions
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createModalSandboxFactory, createModalSandboxFactoryFromSandbox } from "@langchain/modal";
// Create new sandbox per invocation
const factory = createModalSandboxFactory({ imageName: "python:3.12-slim" });
// Or reuse an existing sandbox across invocations
const sandbox = await ModalSandbox.create();
const reuseFactory = createModalSandboxFactoryFromSandbox(sandbox);
```
## Error handling
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ModalSandboxError } from "@langchain/modal";
try {
await sandbox.execute("some command");
} catch (error) {
if (error instanceof ModalSandboxError) {
switch (error.code) {
case "NOT_INITIALIZED":
await sandbox.initialize();
break;
case "COMMAND_TIMEOUT":
console.error("Command took too long");
break;
case "AUTHENTICATION_FAILED":
console.error("Check your Modal token credentials");
break;
}
}
}
```
### Error codes
| Code | Description |
| ------------------------- | --------------------------------------------- |
| `NOT_INITIALIZED` | Sandbox not initialized - call `initialize()` |
| `ALREADY_INITIALIZED` | Cannot initialize twice |
| `AUTHENTICATION_FAILED` | Invalid or missing Modal tokens |
| `SANDBOX_CREATION_FAILED` | Failed to create sandbox |
| `SANDBOX_NOT_FOUND` | Sandbox ID/name not found or expired |
| `COMMAND_TIMEOUT` | Command execution timed out |
| `COMMAND_FAILED` | Command execution failed |
| `FILE_OPERATION_FAILED` | File read/write failed |
| `RESOURCE_LIMIT_EXCEEDED` | CPU, memory, or storage limits exceeded |
| `VOLUME_ERROR` | Volume operation failed |
## Environment variables
| Variable | Description |
| -------------------- | ---------------------- |
| `MODAL_TOKEN_ID` | Modal API token ID |
| `MODAL_TOKEN_SECRET` | Modal API token secret |
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/providers/modal.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).