0
# Configuration
1

2
Comprehensive configuration system for LangGraph CLI applications. Configuration is defined through `langgraph.json` files and validated using typed Python schemas.
3

4
## Capabilities
5

6
### Configuration Validation
7

8
Validate and normalize configuration data from dictionaries or JSON files.
9

10
```python { .api }
11
def validate_config(config: Config) -> Config
12
```
13

14
**Purpose**: Validate and normalize a configuration dictionary
15
**Parameters**:
16
- `config` (Config): Raw configuration dictionary to validate
17
**Returns**: Validated and normalized Config object
18
**Raises**: ValidationError for invalid configuration
19

20
```python { .api }
21
def validate_config_file(config_path: pathlib.Path) -> Config
22
```
23

24
**Purpose**: Load and validate configuration from JSON file
25
**Parameters**:
26
- `config_path` (pathlib.Path): Path to langgraph.json configuration file
27
**Returns**: Validated Config object
28
**Raises**: FileNotFoundError, JSONDecodeError, ValidationError
29

30
**Usage Examples:**
31

32
```python
33
from langgraph_cli.config import validate_config, validate_config_file
34
import pathlib
35

36
# Validate configuration dictionary
37
config_dict = {
38
    "dependencies": ["langchain_openai", "."],
39
    "graphs": {"my_graph": "./src/app.py:graph"},
40
    "python_version": "3.11"
41
}
42
validated_config = validate_config(config_dict)
43

44
# Validate configuration file
45
config_path = pathlib.Path("langgraph.json")
46
config = validate_config_file(config_path)
47
```
48

49
### Docker Generation
50

51
Generate Docker-related files from configuration.
52

53
```python { .api }
54
def config_to_docker(
55
    config: Config,
56
    platform: str = "linux/amd64",
57
    with_apt_package_cache: bool = False,
58
    tag: str = "latest"
59
) -> tuple[str, dict[str, str]]
60
```
61

62
**Purpose**: Generate Dockerfile content from configuration
63
**Parameters**:
64
- `config` (Config): Validated configuration object
65
- `platform` (str): Target platform for Docker build
66
- `with_apt_package_cache` (bool): Include apt package cache optimization
67
- `tag` (str): Docker image tag
68
**Returns**: Tuple of (dockerfile_content, build_contexts)
69

70
```python { .api }
71
def config_to_compose(
72
    config: Config,
73
    image: str,
74
    port: int = DEFAULT_PORT,
75
    docker_compose: Optional[pathlib.Path] = None,
76
    debugger_port: Optional[int] = None,
77
    debugger_base_url: Optional[str] = None,
78
    postgres_uri: Optional[str] = None
79
) -> str
80
```
81

82
**Purpose**: Generate Docker Compose YAML from configuration
83
**Parameters**:
84
- `config` (Config): Validated configuration object
85
- `image` (str): Docker image name to use
86
- `port` (int): Port to expose (default: 8123)
87
- `docker_compose` (Optional[pathlib.Path]): Additional compose file to merge
88
- `debugger_port` (Optional[int]): Port for debugger UI
89
- `debugger_base_url` (Optional[str]): Base URL for debugger
90
- `postgres_uri` (Optional[str]): PostgreSQL connection string
91
**Returns**: Docker Compose YAML content as string
92

93
**Usage Examples:**
94

95
```python
96
from langgraph_cli.config import config_to_docker, config_to_compose
97

98
# Generate Dockerfile
99
dockerfile_content, build_contexts = config_to_docker(
100
    config,
101
    platform="linux/amd64,linux/arm64",
102
    tag="my-app:latest"
103
)
104

105
# Generate Docker Compose
106
compose_yaml = config_to_compose(
107
    config,
108
    image="my-app:latest",
109
    port=8080,
110
    debugger_port=8081
111
)
112
```
113

114
### Image Management
115

116
Determine appropriate Docker images and tags from configuration.
117

118
```python { .api }
119
def default_base_image(config: Config) -> str
120
```
121

122
**Purpose**: Determine the appropriate base Docker image for a configuration
123
**Parameters**:
124
- `config` (Config): Configuration object
125
**Returns**: Docker base image name (e.g., "python:3.11-slim")
126

127
```python { .api }
128
def docker_tag(
129
    config: Config,
130
    image: Optional[str] = None,
131
    platform: Optional[str] = None
132
) -> str
133
```
134

135
**Purpose**: Generate appropriate Docker tag from configuration
136
**Parameters**:
137
- `config` (Config): Configuration object
138
- `image` (Optional[str]): Custom image name override
139
- `platform` (Optional[str]): Target platform specification
140
**Returns**: Full Docker image tag
141

142
**Usage Examples:**
143

144
```python
145
from langgraph_cli.config import default_base_image, docker_tag
146

147
# Get default base image
148
base_image = default_base_image(config)  # "python:3.11-slim"
149

150
# Generate Docker tag
151
tag = docker_tag(config, image="my-app", platform="linux/amd64")
152
```
153

154
## Configuration Schema
155

156
### Core Configuration
157

158
```python { .api }
159
class Config(TypedDict, total=False):
160
    python_version: str
161
    node_version: str
162
    api_version: str
163
    base_image: str
164
    image_distro: Distros
165
    dependencies: list[str]
166
    graphs: dict[str, str]
167
    env: Union[str, dict[str, str]]
168
    dockerfile_lines: list[str]
169
    pip_config_file: str
170
    pip_installer: str
171
    store: StoreConfig
172
    auth: AuthConfig
173
    http: HttpConfig
174
    checkpointer: CheckpointerConfig
175
    ui: dict[str, Any]
176
    keep_pkg_tools: bool
177
```
178

179
**Configuration Properties:**
180

181
- **python_version**: Python runtime version ("3.11", "3.12", "3.13")
182
- **node_version**: Node.js runtime version for JavaScript dependencies
183
- **api_version**: LangGraph API server version to use
184
- **base_image**: Custom Docker base image override
185
- **image_distro**: Linux distribution ("debian", "wolfi", "bullseye", "bookworm")
186
- **dependencies**: List of Python/Node.js packages to install
187
- **graphs**: Mapping of graph IDs to import paths (e.g., "./src/app.py:graph")
188
- **env**: Environment variables (file path string or dictionary)
189
- **dockerfile_lines**: Additional Docker instructions to include
190
- **pip_config_file**: Path to custom pip configuration file
191
- **pip_installer**: Package installer ("auto", "pip", "uv")
192
- **store**: Long-term memory store configuration
193
- **auth**: Custom authentication configuration
194
- **http**: HTTP server and routing configuration
195
- **checkpointer**: State checkpointing configuration
196
- **ui**: UI component definitions
197
- **keep_pkg_tools**: Retain packaging tools in final image
198

199
### Store Configuration
200

201
```python { .api }
202
class StoreConfig(TypedDict, total=False):
203
    index: IndexConfig
204
    ttl: TTLConfig
205

206
class IndexConfig(TypedDict, total=False):
207
    dims: int  # Required
208
    embed: str  # Required
209
    fields: Optional[list[str]]
210

211
class TTLConfig(TypedDict, total=False):
212
    refresh_on_read: bool
213
    default_ttl: Optional[float]
214
    sweep_interval_minutes: Optional[int]
215
```
216

217
**Store Configuration:**
218

219
- **IndexConfig**: Vector search configuration
220
  - `dims`: Embedding vector dimensions (required)
221
  - `embed`: Embedding model reference (required, e.g., "openai:text-embedding-3-large")
222
  - `fields`: JSON fields to extract and embed (optional)
223
- **TTLConfig**: Time-to-live behavior
224
  - `refresh_on_read`: Refresh TTL on read operations
225
  - `default_ttl`: Default TTL in minutes for new items
226
  - `sweep_interval_minutes`: Cleanup interval for expired items
227

228
### Authentication Configuration
229

230
```python { .api }
231
class AuthConfig(TypedDict, total=False):
232
    path: str  # Required
233
    disable_studio_auth: bool
234
    openapi: SecurityConfig
235

236
class SecurityConfig(TypedDict, total=False):
237
    type: str
238
    scheme: str
239
    name: str
240
```
241

242
**Authentication Properties:**
243

244
- **path**: Path to Auth() class instance (required)
245
- **disable_studio_auth**: Disable LangSmith authentication for Studio integration
246
- **openapi**: OpenAPI security configuration for API documentation
247

248
### HTTP Configuration
249

250
```python { .api }
251
class HttpConfig(TypedDict, total=False):
252
    app: str
253
    disable_assistants: bool
254
    disable_threads: bool
255
    disable_runs: bool
256
    disable_store: bool
257
    disable_mcp: bool
258
    disable_meta: bool
259
    cors: CorsConfig
260
    configurable_headers: ConfigurableHeaderConfig
261
    logging_headers: ConfigurableHeaderConfig
262

263
class CorsConfig(TypedDict, total=False):
264
    allow_origins: list[str]
265
    allow_methods: list[str]
266
    allow_headers: list[str]
267
    allow_credentials: bool
268
    max_age: int
269

270
class ConfigurableHeaderConfig(TypedDict, total=False):
271
    request: dict[str, str]
272
    response: dict[str, str]
273
```
274

275
**HTTP Configuration Properties:**
276

277
- **app**: Path to custom Starlette/FastAPI application
278
- **disable_***: Disable specific API route groups
279
- **cors**: Cross-Origin Resource Sharing configuration
280
- **configurable_headers**: Custom header handling for requests/responses
281
- **logging_headers**: Headers to include in access logs
282

283
### Checkpointer Configuration
284

285
```python { .api }
286
class CheckpointerConfig(TypedDict, total=False):
287
    ttl: ThreadTTLConfig
288

289
class ThreadTTLConfig(TypedDict, total=False):
290
    default_ttl: Optional[float]
291
    sweep_interval_minutes: Optional[int]
292
```
293

294
**Checkpointer Properties:**
295

296
- **ttl**: Time-to-live configuration for checkpointed conversation threads
297

298
## Configuration Examples
299

300
### Minimal Configuration
301

302
```json
303
{
304
  "dependencies": ["langchain_openai", "."],
305
  "graphs": {
306
    "main": "./src/graph.py:compiled_graph"
307
  }
308
}
309
```
310

311
### Complete Development Configuration
312

313
```json
314
{
315
  "python_version": "3.11",
316
  "dependencies": [
317
    "langchain_openai",
318
    "langchain_community",
319
    "."
320
  ],
321
  "graphs": {
322
    "chat_agent": "./src/agents/chat.py:agent",
323
    "rag_system": "./src/rag/pipeline.py:rag_graph"
324
  },
325
  "env": "./.env.development",
326
  "store": {
327
    "index": {
328
      "dims": 1536,
329
      "embed": "openai:text-embedding-3-small",
330
      "fields": ["content", "metadata.title"]
331
    },
332
    "ttl": {
333
      "default_ttl": 1440,
334
      "sweep_interval_minutes": 60
335
    }
336
  },
337
  "http": {
338
    "cors": {
339
      "allow_origins": ["http://localhost:3000"],
340
      "allow_credentials": true
341
    }
342
  }
343
}
344
```
345

346
### Production Configuration
347

348
```json
349
{
350
  "python_version": "3.12",
351
  "image_distro": "wolfi",
352
  "dependencies": [
353
    "langchain_openai==0.1.7",
354
    "langchain_community==0.2.1",
355
    "."
356
  ],
357
  "graphs": {
358
    "production_agent": "./src/production_graph.py:graph"
359
  },
360
  "env": {
361
    "LOG_LEVEL": "INFO",
362
    "ENVIRONMENT": "production"
363
  },
364
  "auth": {
365
    "path": "./src/auth.py:custom_auth"
366
  },
367
  "http": {
368
    "disable_meta": true,
369
    "cors": {
370
      "allow_origins": ["https://myapp.example.com"]
371
    }
372
  },
373
  "dockerfile_lines": [
374
    "RUN apt-get update && apt-get install -y curl",
375
    "COPY config/ /app/config/"
376
  ]
377
}
378
```
379

380
## Validation and Error Handling
381

382
The configuration system provides comprehensive validation:
383

384
- **Type checking**: All fields validated against TypedDict schemas
385
- **Required field validation**: Missing required fields raise ValidationError
386
- **Format validation**: Import paths, version strings, and URIs validated
387
- **Dependency validation**: Package specifications checked for format
388
- **Graph path validation**: Import paths verified for correct module:variable format
389

390
Common validation errors:
391

392
- **Invalid Python version**: Must be "3.11", "3.12", or "3.13"
393
- **Invalid graph path**: Must follow "module.path:variable" format
394
- **Missing embedding dimensions**: IndexConfig requires both `dims` and `embed`
395
- **Invalid dependency format**: Package specifications must be valid pip requirements