0
# Core Application & Client
1
2
Primary interfaces for defining applications and managing authentication and object lookup with Modal's cloud platform.
3
4
## Capabilities
5
6
### App Class
7
8
Main application container for defining and deploying Modal functions and resources. All serverless functions, classes, and resources are defined within the context of an App.
9
10
```python { .api }
11
class App:
12
def __init__(self, name: str = None):
13
"""
14
Create a new Modal application.
15
16
Parameters:
17
- name: Optional name for the app. If not provided, a name will be generated.
18
"""
19
20
def function(
21
self,
22
image: Optional["Image"] = None,
23
schedule: Optional[Union["Cron", "Period"]] = None,
24
secrets: Optional[list["Secret"]] = None,
25
volumes: Optional[dict[str, "Volume"]] = None,
26
network_file_systems: Optional[dict[str, "NetworkFileSystem"]] = None,
27
cloud_bucket_mounts: Optional[dict[str, "CloudBucketMount"]] = None,
28
memory: Optional[int] = None,
29
cpu: Optional[float] = None,
30
gpu: Optional[str] = None,
31
timeout: Optional[int] = None,
32
retries: Optional[Union[int, "Retries"]] = None,
33
concurrency_limit: Optional[int] = None,
34
allow_concurrent_inputs: Optional[int] = None,
35
container_idle_timeout: Optional[int] = None,
36
keep_warm: Optional[int] = None,
37
**kwargs
38
):
39
"""
40
Decorator to define a serverless function within the app.
41
42
Parameters:
43
- image: Container image to run the function in
44
- schedule: Schedule for automatic execution (Cron or Period)
45
- secrets: List of secrets to inject as environment variables
46
- volumes: Dictionary mapping mount paths to Volume objects
47
- network_file_systems: Dictionary mapping mount paths to NetworkFileSystem objects
48
- cloud_bucket_mounts: Dictionary mapping mount paths to CloudBucketMount objects
49
- memory: Memory limit in MB
50
- cpu: CPU allocation (fractional values supported)
51
- gpu: GPU specification string (e.g., "any", "a10g", "h100")
52
- timeout: Function timeout in seconds
53
- retries: Retry policy for failed executions
54
- concurrency_limit: Maximum concurrent executions
55
- allow_concurrent_inputs: Allow concurrent inputs per container
56
- container_idle_timeout: How long to keep containers warm
57
- keep_warm: Number of containers to keep warm
58
59
Returns:
60
Function decorator
61
"""
62
63
def cls(
64
self,
65
image: Image = None,
66
secrets: list[Secret] = None,
67
volumes: dict[str, Volume] = None,
68
mounts: list[Mount] = None,
69
memory: int = None,
70
cpu: float = None,
71
gpu: GPU_T = None,
72
timeout: int = None,
73
retries: Retries = None,
74
concurrency_limit: int = None,
75
container_idle_timeout: int = None,
76
keep_warm: int = None,
77
**kwargs
78
):
79
"""
80
Decorator to define a serverless class within the app.
81
82
Parameters:
83
- image: Container image to run the class in
84
- secrets: List of secrets to inject as environment variables
85
- volumes: Dictionary mapping mount paths to Volume objects
86
- mounts: List of mount objects for code and data
87
- memory: Memory limit in MB
88
- cpu: CPU allocation
89
- gpu: GPU configuration
90
- timeout: Method timeout in seconds
91
- retries: Retry policy for failed method calls
92
- concurrency_limit: Maximum concurrent class instances
93
- container_idle_timeout: How long to keep containers warm
94
- keep_warm: Number of containers to keep warm
95
96
Returns:
97
Class decorator
98
"""
99
100
def local_entrypoint(self):
101
"""
102
Decorator to define a local entry point that can call remote functions.
103
104
The decorated function will run locally and can invoke remote functions
105
defined in the same app.
106
107
Returns:
108
Function decorator
109
"""
110
111
def deploy(self, name: str = None):
112
"""
113
Deploy the app to Modal cloud.
114
115
Parameters:
116
- name: Optional deployment name
117
118
Returns:
119
Deployed app handle
120
"""
121
122
def run(self, detach: bool = False):
123
"""
124
Run the app, executing the local entrypoint if defined.
125
126
Parameters:
127
- detach: Run in detached mode
128
"""
129
130
def stop(self):
131
"""
132
Stop a running app.
133
"""
134
135
def list_objects(self):
136
"""
137
List all objects (functions, classes, etc.) defined in the app.
138
139
Returns:
140
List of app objects
141
"""
142
```
143
144
### Client Class
145
146
Client for interacting with Modal's API, managing authentication, and looking up deployed objects.
147
148
```python { .api }
149
class Client:
150
@classmethod
151
def from_env(
152
cls,
153
profile: str = None,
154
token_id: str = None,
155
token_secret: str = None
156
):
157
"""
158
Create a client from environment variables or profile.
159
160
Parameters:
161
- profile: Named profile to use for authentication
162
- token_id: Override token ID from environment
163
- token_secret: Override token secret from environment
164
165
Returns:
166
Authenticated Client instance
167
"""
168
169
def lookup(
170
self,
171
label: str,
172
namespace: str = None,
173
create_if_missing: bool = False
174
):
175
"""
176
Look up a deployed object by label.
177
178
Parameters:
179
- label: Label of the object to look up
180
- namespace: Namespace to search in
181
- create_if_missing: Create the object if it doesn't exist
182
183
Returns:
184
The deployed object
185
"""
186
187
def list(self, namespace: str = None):
188
"""
189
List objects in the account.
190
191
Parameters:
192
- namespace: Optional namespace to filter by
193
194
Returns:
195
List of deployed objects
196
"""
197
```
198
199
## Usage Examples
200
201
### Basic App Definition
202
203
```python
204
import modal
205
206
# Create an app
207
app = modal.App("my-application")
208
209
# Define a simple function
210
@app.function()
211
def hello(name: str) -> str:
212
return f"Hello, {name}!"
213
214
# Local entrypoint to test the function
215
@app.local_entrypoint()
216
def main():
217
result = hello.remote("World")
218
print(result) # "Hello, World!"
219
```
220
221
### App with Custom Configuration
222
223
```python
224
import modal
225
226
app = modal.App("data-processor")
227
228
# Custom image with dependencies
229
image = modal.Image.debian_slim().pip_install("pandas", "numpy")
230
231
# Function with resource configuration
232
@app.function(
233
image=image,
234
memory=2048, # 2GB memory
235
timeout=600, # 10 minute timeout
236
secrets=[modal.Secret.from_name("api-key")],
237
volumes={"/data": modal.Volume.from_name("dataset")}
238
)
239
def process_data(filename: str):
240
import pandas as pd
241
df = pd.read_csv(f"/data/{filename}")
242
return df.groupby('category').sum().to_dict()
243
244
@app.local_entrypoint()
245
def main():
246
result = process_data.remote("sales_data.csv")
247
print(result)
248
```
249
250
### Client Usage
251
252
```python
253
import modal
254
255
# Create client from environment
256
client = modal.Client.from_env()
257
258
# Look up a deployed function
259
my_function = client.lookup("my-function")
260
261
# Call the remote function
262
result = my_function.remote("input_data")
263
```
264
265
### Deployment
266
267
```python
268
import modal
269
270
app = modal.App("production-app")
271
272
@app.function()
273
def my_function():
274
return "Hello from production!"
275
276
# Deploy to Modal cloud
277
if __name__ == "__main__":
278
# Deploy the app
279
app.deploy("v1.0")
280
281
# Or run locally for development
282
# app.run()
283
```