Skills › Scientific Agent Skills › modal › api_reference.md

api_reference.md

253 lines · skills/modal/references/api_reference.md at 5f2bc03

Starts an agent Involves a person

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Modal API Reference

3Checked against installed `modal==1.6.0` signatures and official

4[Python SDK reference](https://modal.com/docs/sdk/py/latest) /

5[release notes](https://modal.com/docs/sdk/py/releases). SDK object construction was

6tested without contacting Modal; cloud behavior below is documentation-verified.

Modal API Reference

Checked against installed modal==1.6.0 signatures and official Python SDK reference / release notes. SDK object construction was tested without contacting Modal; cloud behavior below is documentation-verified.

Raw lines 1 to 7

8## Core Classes

Core Classes

Raw lines 8 to 9

10### modal.App

12The main unit of deployment. Groups related functions.

14```python

15app = modal.App("my-app")

16```

18| Method | Description |

19|--------|-------------|

20| `app.function(**kwargs)` | Decorator to register a function |

21| `app.cls(**kwargs)` | Decorator to register a class |

22| `app.local_entrypoint()` | Decorator for local entry point |

modal.App

The main unit of deployment. Groups related functions.

app = modal.App("my-app")

Method	Description
`app.function(**kwargs)`	Decorator to register a function
`app.cls(**kwargs)`	Decorator to register a class
`app.local_entrypoint()`	Decorator for local entry point

Raw lines 10 to 23

24### modal.Function

26A serverless function backed by an autoscaling container pool.

28| Method | Description |

29|--------|-------------|

30| `.remote(*args)` | Execute in the cloud (sync) |

31| `.local(*args)` | Execute locally |

32| `.spawn(*args)` | Execute async, returns `FunctionCall` |

33| `.map(inputs)` | Parallel execution over inputs |

34| `.starmap(inputs)` | Parallel execution with multiple args |

35| `.for_each(inputs)` | Like `.map()` but discards outputs |

36| `.spawn_map(inputs)` | Submit asynchronous inputs; returns `None`, not result handles |

37| `.from_name(app, fn)` | Reference a deployed function (replaces deprecated `.lookup`) |

38| `.hydrate()` | Force-fetch server metadata (replaces deprecated `.resolve()`) |

39| `.with_options(gpu=, ...)` | New autoscaling variant with overridden config |

40| `.with_concurrency(max_inputs=, target_inputs=)` | Override input concurrency at invocation |

41| `.with_batching(max_batch_size=, wait_ms=)` | Override dynamic batching at invocation |

42| `.update_autoscaler(**kwargs)` | Dynamic scaling update |

modal.Function

A serverless function backed by an autoscaling container pool.

Method	Description
`.remote(*args)`	Execute in the cloud (sync)
`.local(*args)`	Execute locally
`.spawn(*args)`	Execute async, returns `FunctionCall`
`.map(inputs)`	Parallel execution over inputs
`.starmap(inputs)`	Parallel execution with multiple args
`.for_each(inputs)`	Like `.map()` but discards outputs
`.spawn_map(inputs)`	Submit asynchronous inputs; returns `None`, not result handles
`.from_name(app, fn)`	Reference a deployed function (replaces deprecated `.lookup`)
`.hydrate()`	Force-fetch server metadata (replaces deprecated `.resolve()`)
`.with_options(gpu=, ...)`	New autoscaling variant with overridden config
`.with_concurrency(max_inputs=, target_inputs=)`	Override input concurrency at invocation
`.with_batching(max_batch_size=, wait_ms=)`	Override dynamic batching at invocation
`.update_autoscaler(**kwargs)`	Dynamic scaling update

Raw lines 24 to 43

Starts an agent spawn :32

44### modal.Cls

46A serverless class with lifecycle hooks.

48```python

49@app.cls(gpu="L40S")

50class MyClass:

51 @modal.enter()

52 def setup(self): ...

54 @modal.method()

55 def run(self, data): ...

57 @modal.exit()

58 def cleanup(self): ...

59```

61| Decorator | Description |

62|-----------|-------------|

63| `@modal.enter()` | Container startup hook |

64| `@modal.exit()` | Container shutdown hook |

65| `@modal.method()` | Expose as callable method |

66| `field: str = modal.parameter()` | Class-level parameter descriptor (not a decorator) |

68Look up a deployed Cls with `Model = modal.Cls.from_name("app", "Model")`, then

69instantiate before calling: `Model().method.remote(...)`. Override config at invocation

70with `Model.with_options(gpu="H200", max_containers=10)`.

71SDK 1.6 rejects custom `__init__`; put initialization in `@modal.enter()`.

72Variant pools scale independently; `.with_options()` cannot set `min_containers`.

modal.Cls

A serverless class with lifecycle hooks.

@app.cls(gpu="L40S")
class MyClass:
    @modal.enter()
    def setup(self): ...

    @modal.method()
    def run(self, data): ...

    @modal.exit()
    def cleanup(self): ...

Decorator	Description
`@modal.enter()`	Container startup hook
`@modal.exit()`	Container shutdown hook
`@modal.method()`	Expose as callable method
`field: str = modal.parameter()`	Class-level parameter descriptor (not a decorator)

Look up a deployed Cls with Model = modal.Cls.from_name("app", "Model"), then instantiate before calling: Model().method.remote(...). Override config at invocation with Model.with_options(gpu="H200", max_containers=10). SDK 1.6 rejects custom __init__; put initialization in @modal.enter(). Variant pools scale independently; .with_options() cannot set min_containers.

Raw lines 44 to 73

74## Image

Image

Raw lines 74 to 75

76### modal.Image

78Defines the container environment.

80| Method | Description |

81|--------|-------------|

82| `.debian_slim(python_version=)` | Debian base image |

83| `.from_registry(tag)` | Docker Hub image |

84| `.from_dockerfile(path)` | Build from Dockerfile |

85| `.micromamba(python_version=)` | Conda/mamba base |

86| `.uv_pip_install(*pkgs)` | Install with uv (recommended) |

87| `.pip_install(*pkgs)` | Install with pip |

88| `.pip_install_from_requirements(path)` | Install from file |

89| `.uv_sync(project_dir)` | Install the project's locked uv environment |

90| `.apt_install(*pkgs)` | Install system packages |

91| `.run_commands(*cmds)` | Run shell commands |

92| `.run_function(fn)` | Run Python during build |

93| `.add_local_dir(local, remote)` | Add directory |

94| `.add_local_file(local, remote)` | Add single file |

95| `.add_local_python_source(module)` | Add Python module |

96| `.env(dict)` | Set environment variables |

97| `.pipe(recipe_fn)` | Apply a reusable Image recipe |

98| `.imports()` | Context manager for remote imports |

100> `add_local_dir`/`add_local_file`/`add_local_python_source` replace the deprecated

101> `copy_local_*` methods and the removed `modal.Mount` object / `mount=` / `context_mount=`

102> parameters.

103

modal.Image

Defines the container environment.

Method	Description
`.debian_slim(python_version=)`	Debian base image
`.from_registry(tag)`	Docker Hub image
`.from_dockerfile(path)`	Build from Dockerfile
`.micromamba(python_version=)`	Conda/mamba base
`.uv_pip_install(*pkgs)`	Install with uv (recommended)
`.pip_install(*pkgs)`	Install with pip
`.pip_install_from_requirements(path)`	Install from file
`.uv_sync(project_dir)`	Install the project's locked uv environment
`.apt_install(*pkgs)`	Install system packages
`.run_commands(*cmds)`	Run shell commands
`.run_function(fn)`	Run Python during build
`.add_local_dir(local, remote)`	Add directory
`.add_local_file(local, remote)`	Add single file
`.add_local_python_source(module)`	Add Python module
`.env(dict)`	Set environment variables
`.pipe(recipe_fn)`	Apply a reusable Image recipe
`.imports()`	Context manager for remote imports

add_local_dir/add_local_file/add_local_python_source replace the deprecated copy_local_* methods and the removed modal.Mount object / mount= / context_mount= parameters.

Raw lines 76 to 103

104## Storage

105

Storage

Raw lines 104 to 105

106### modal.Volume

107

108Distributed persistent file storage.

109

110```python

111vol = modal.Volume.from_name("name", create_if_missing=True)

112```

113

114| Method | Description |

115|--------|-------------|

116| `.from_name(name)` | Reference or create a volume |

117| `.commit()` | Force immediate commit |

118| `.reload()` | Refresh to see other containers' writes |

119| `.with_mount_options(read_only=, sub_path=)` | Read-only or subdirectory mount |

120

121Mount: `@app.function(volumes={"/path": vol})`

122

modal.Volume

Distributed persistent file storage.

vol = modal.Volume.from_name("name", create_if_missing=True)

Method	Description
`.from_name(name)`	Reference or create a volume
`.commit()`	Force immediate commit
`.reload()`	Refresh to see other containers' writes
`.with_mount_options(read_only=, sub_path=)`	Read-only or subdirectory mount

Mount: @app.function(volumes={"/path": vol})

Raw lines 106 to 122

123### modal.NetworkFileSystem

124

125Legacy shared storage (superseded by Volume).

126

modal.NetworkFileSystem

Legacy shared storage (superseded by Volume).

Raw lines 123 to 126

127## Sandboxes

128

Sandboxes

Raw lines 127 to 128

129### modal.Sandbox

130

131Isolated, programmatically controlled containers for running untrusted or

132dynamically generated code.

133

134```python

135app = modal.App.lookup("my-app", create_if_missing=True)

136sb = modal.Sandbox.create(app=app, image=modal.Image.debian_slim(), timeout=60, block_network=True)

137try:

138 proc = sb.exec("python", "-c", "print(2 ** 10)")

139 stdout = proc.stdout.read()

140 proc.wait()

141 if proc.returncode != 0:

142 raise RuntimeError("Sandbox command failed")

143finally:

144 sb.terminate(wait=True)

145```

146

147| Method | Description |

148|--------|-------------|

149| `.create(app=, image=, ...)` | Launch and wait for scheduling (SDK 1.6) |

150| `.exec(*cmd)` | Run a command, returns a process handle |

151| `.filesystem.read_text(path)` | Read a Sandbox file into a string |

152| `.filesystem.write_text(text, path)` | Write a string; content argument comes first |

153| `.filesystem.copy_from_local(local, remote)` | Stream a local file to the Sandbox |

154| `.filesystem.copy_to_local(remote, local)` | Stream a Sandbox file to local storage |

155| `.snapshot_filesystem(timeout=55, ttl=2592000)` | Image snapshot, default retention 30 days |

156| `.terminate(wait=True)` | Stop and wait for termination confirmation |

157

158Restrict connectivity with `inbound_cidr_allowlist=[...]` / `outbound_cidr_allowlist=[...]`.

159Use `block_network=True` when egress is unnecessary. Allowlisting a private CIDR is

160not a substitute for selecting the intended destinations. Network restrictions do

161not remove Secrets or data mounted into the container.

162`Sandbox.create()` can raise `ResourceExhaustedError` if scheduling fails. The old

163`Sandbox.open/ls/mkdir/rm/watch` APIs are removed; use `.filesystem`.

164Pass `ttl=None` explicitly if a filesystem snapshot must not expire, and track its

165Image ID. See [Sandbox snapshots](https://modal.com/docs/guide/sandbox-snapshots).

166

modal.Sandbox

Isolated, programmatically controlled containers for running untrusted or dynamically generated code.

app = modal.App.lookup("my-app", create_if_missing=True)
sb = modal.Sandbox.create(app=app, image=modal.Image.debian_slim(), timeout=60, block_network=True)
try:
    proc = sb.exec("python", "-c", "print(2 ** 10)")
    stdout = proc.stdout.read()
    proc.wait()
    if proc.returncode != 0:
        raise RuntimeError("Sandbox command failed")
finally:
    sb.terminate(wait=True)

Method	Description
`.create(app=, image=, ...)`	Launch and wait for scheduling (SDK 1.6)
`.exec(*cmd)`	Run a command, returns a process handle
`.filesystem.read_text(path)`	Read a Sandbox file into a string
`.filesystem.write_text(text, path)`	Write a string; content argument comes first
`.filesystem.copy_from_local(local, remote)`	Stream a local file to the Sandbox
`.filesystem.copy_to_local(remote, local)`	Stream a Sandbox file to local storage
`.snapshot_filesystem(timeout=55, ttl=2592000)`	Image snapshot, default retention 30 days
`.terminate(wait=True)`	Stop and wait for termination confirmation

Restrict connectivity with inbound_cidr_allowlist=[...] / outbound_cidr_allowlist=[...]. Use block_network=True when egress is unnecessary. Allowlisting a private CIDR is not a substitute for selecting the intended destinations. Network restrictions do not remove Secrets or data mounted into the container. Sandbox.create() can raise ResourceExhaustedError if scheduling fails. The old Sandbox.open/ls/mkdir/rm/watch APIs are removed; use .filesystem. Pass ttl=None explicitly if a filesystem snapshot must not expire, and track its Image ID. See Sandbox snapshots.

Raw lines 129 to 166

Involves a person and wait :149

Involves a person Stop and wait :156

167## Secrets

168

Secrets

Raw lines 167 to 168

169### modal.Secret

170

171Secure credential injection.

172

173| Method | Description |

174|--------|-------------|

175| `.from_name(name)` | Reference a named secret |

176| `.from_dict(dict)` | Create inline (dev only) |

177| `.from_dotenv()` | Load from .env file |

178

179Usage: `@app.function(secrets=[modal.Secret.from_name("x")])`

180

181Access in function: `os.environ["KEY"]`

182

modal.Secret

Secure credential injection.

Method	Description
`.from_name(name)`	Reference a named secret
`.from_dict(dict)`	Create inline (dev only)
`.from_dotenv()`	Load from .env file

Usage: @app.function(secrets=[modal.Secret.from_name("x")])

Access in function: os.environ["KEY"]

Raw lines 169 to 182

183## Scheduling

184

Scheduling

Raw lines 183 to 184

185### modal.Cron

186

187```python

188schedule = modal.Cron("0 9 * * *") # Cron syntax

189```

190

modal.Cron

schedule = modal.Cron("0 9 * * *")  # Cron syntax

Raw lines 185 to 190

191### modal.Period

192

193```python

194schedule = modal.Period(hours=6) # Fixed interval

195```

196

197Usage: `@app.function(schedule=modal.Cron("..."))`

198

modal.Period

schedule = modal.Period(hours=6)  # Fixed interval

Usage: @app.function(schedule=modal.Cron("..."))

Raw lines 191 to 198

199## Web

200

Web

Raw lines 199 to 200

201### Decorators

202

203| Decorator | Description |

204|-----------|-------------|

205| `@modal.fastapi_endpoint()` | Simple FastAPI endpoint |

206| `@modal.asgi_app()` | Full ASGI app (FastAPI, Starlette) |

207| `@modal.wsgi_app()` | Full WSGI app (Flask, Django) |

208| `@modal.web_server(port=)` | Custom web server |

209

Decorators

Decorator	Description
`@modal.fastapi_endpoint()`	Simple FastAPI endpoint
`@modal.asgi_app()`	Full ASGI app (FastAPI, Starlette)
`@modal.wsgi_app()`	Full WSGI app (Flask, Django)
`@modal.web_server(port=)`	Custom web server

Raw lines 201 to 209

210### Function Modifiers

211

212| Decorator | Description |

213|-----------|-------------|

214| `@modal.concurrent(max_inputs=)` | Handle multiple inputs per container |

215| `@modal.batched(max_batch_size=, wait_ms=)` | Dynamic input batching |

216

Function Modifiers

Decorator	Description
`@modal.concurrent(max_inputs=)`	Handle multiple inputs per container
`@modal.batched(max_batch_size=, wait_ms=)`	Dynamic input batching

Raw lines 210 to 216

217## GPU Strings

218

219| String | GPU |

220|--------|-----|

221| `"T4"` | NVIDIA T4 16GB |

222| `"L4"` | NVIDIA L4 24GB |

223| `"A10"` | NVIDIA A10 24GB |

224| `"L40S"` | NVIDIA L40S 48GB |

225| `"A100-40GB"` | NVIDIA A100 40GB |

226| `"A100-80GB"` | NVIDIA A100 80GB |

227| `"H100"` | NVIDIA H100 80GB |

228| `"H100!"` | H100 (no auto-upgrade) |

229| `"H200"` | NVIDIA H200 141GB |

230| `"B200"` | NVIDIA B200 192GB |

231| `"B200+"` | B200 or B300, B200 price |

232| `"B300"` | NVIDIA B300 288GB, CUDA 13.1+ |

233| `"RTX-PRO-6000"` | NVIDIA RTX PRO 6000 Blackwell 96GB |

234| `"H100:4"` | 4x H100 |

235

GPU Strings

String	GPU
`"T4"`	NVIDIA T4 16GB
`"L4"`	NVIDIA L4 24GB
`"A10"`	NVIDIA A10 24GB
`"L40S"`	NVIDIA L40S 48GB
`"A100-40GB"`	NVIDIA A100 40GB
`"A100-80GB"`	NVIDIA A100 80GB
`"H100"`	NVIDIA H100 80GB
`"H100!"`	H100 (no auto-upgrade)
`"H200"`	NVIDIA H200 141GB
`"B200"`	NVIDIA B200 192GB
`"B200+"`	B200 or B300, B200 price
`"B300"`	NVIDIA B300 288GB, CUDA 13.1+
`"RTX-PRO-6000"`	NVIDIA RTX PRO 6000 Blackwell 96GB
`"H100:4"`	4x H100

Raw lines 217 to 235

236## CLI Commands

237

238| Command | Description |

239|---------|-------------|

240| `modal setup` | Authenticate |

241| `modal run <file>` | Run local entrypoint |

242| `modal serve <file>` | Dev server with hot reload |

243| `modal deploy <file>` | Production deployment |

244| `modal app list` | List deployed apps |

245| `modal app stop <name>` | Stop an app |

246| `modal volume create <name>` | Create volume |

247| `modal volume ls <name>` | List volume files |

248| `modal volume put <name> <file>` | Upload to volume |

249| `modal volume get <name> <file>` | Download from volume |

250| `modal secret create <name> K=V` | Create secret |

251| `modal secret list` | List secrets |

252| `modal secret delete <name>` | Delete secret |

253| `modal token set` | Set auth token |

CLI Commands

Command	Description
`modal setup`	Authenticate
`modal run <file>`	Run local entrypoint
`modal serve <file>`	Dev server with hot reload
`modal deploy <file>`	Production deployment
`modal app list`	List deployed apps
`modal app stop <name>`	Stop an app
`modal volume create <name>`	Create volume
`modal volume ls <name>`	List volume files
`modal volume put <name> <file>`	Upload to volume
`modal volume get <name> <file>`	Download from volume
`modal secret create <name> K=V`	Create secret
`modal secret list`	List secrets
`modal secret delete <name>`	Delete secret
`modal token set`	Set auth token

Raw lines 236 to 253