Implementation:Langchain ai Langgraph CLI Config Schema

Knowledge Sources	Langchain_ai_Langgraph
Domains	CLI, Configuration
Last Updated	2026-02-11 16:00 GMT

Overview

The CLI configuration schema (`schema.json`) defines the JSON Schema for the `langgraph.json` configuration file, specifying all valid fields for deploying LangGraph applications including graphs, dependencies, environment, store, auth, HTTP, checkpointer, and webhooks settings.

Description

This JSON Schema file serves as the authoritative specification for the `langgraph.json` configuration file used by the LangGraph CLI and deployment tooling. The top-level `Config` definition uses a `oneOf` discriminator to support two deployment modes: Python deployments (requiring `dependencies` and `graphs`) and Node.js deployments (requiring `node_version` and `graphs`). Each mode shares many common optional fields but differs in runtime-specific settings like `python_version` versus `node_version`.

The schema defines a rich hierarchy of sub-configurations. `AuthConfig` specifies custom authentication logic with a path to an `Auth()` class, OpenAPI security scheme definitions, cache settings, and an option to disable Studio authentication. `HttpConfig` controls the HTTP server with fields for CORS rules, custom app mounting, route disabling (assistants, threads, runs, store, MCP, A2A, webhooks, UI), configurable headers, middleware ordering, and mount prefix. `CheckpointerConfig` manages state checkpointing with TTL-based cleanup via `ThreadTTLConfig` and serialization settings via `SerdeConfig`. `StoreConfig` configures the long-term memory store with optional vector indexing through `IndexConfig` (embedding model, dimensions, field selection) and TTL behavior through `TTLConfig`. `WebhooksConfig` handles outbound event delivery with URL validation policies, header templates supporting environment variable interpolation, and security controls.

The schema also includes fields for Docker image customization (`base_image`, `image_distro`, `dockerfile_lines`, `keep_pkg_tools`), package management (`pip_installer`, `pip_config_file`), encryption (`EncryptionConfig`), and UI component definitions. This schema version is the current (latest) version and includes support for `bookworm` as an image distribution option for Python deployments.

Usage

This schema is used by the LangGraph CLI to validate `langgraph.json` configuration files before building and deploying LangGraph applications. IDEs and editors can reference this schema for autocompletion and inline validation when editing deployment configurations.

Code Reference

Source Location

• Repository: Langchain_ai_Langgraph
• File: libs/cli/schemas/schema.json

Signature

{
  "$ref": "#/$defs/Config",
  "title": "LangGraph CLI Configuration",
  "description": "Configuration schema for langgraph-cli",
  "version": "v0",
  "$defs": {
    "Config": { "oneOf": [ /* Python config */, /* Node.js config */ ] },
    "AuthConfig": { /* path, openapi, cache, disable_studio_auth */ },
    "HttpConfig": { /* app, cors, disable_*, configurable_headers, ... */ },
    "CheckpointerConfig": { /* ttl, serde, sweep_limit */ },
    "StoreConfig": { /* index, ttl */ },
    "IndexConfig": { /* embed, dims, fields */ },
    "WebhooksConfig": { /* url, headers, env_prefix */ },
    "CorsConfig": { /* allow_origins, allow_methods, allow_headers, ... */ },
    "EncryptionConfig": { /* path */ },
    ...
  }
}

Import

# Referenced by the CLI tooling; not imported as Python code.
# Located at: libs/cli/schemas/schema.json

I/O Contract

Top-Level Config (Python Deployment)
Field	Type	Required	Description
`dependencies`	`array[string]`	Yes	Python dependencies to install from PyPI or local paths
`graphs`	`object`	Yes	Named graph definitions pointing to Python objects
`python_version`	`string`	No	Python version (`3.11`, `3.12`, `3.13`)
`env`	string`	No	Environment variables as dict or path to `.env` file
`auth`	null`	No	Custom authentication configuration
`http`	null`	No	HTTP server configuration
`store`	null`	No	Long-term memory store configuration
`checkpointer`	null`	No	State checkpointing configuration
`webhooks`	null`	No	Outbound webhook event delivery
`encryption`	null`	No	At-rest encryption configuration
`base_image`	null`	No	Base Docker image
`image_distro`	debian | wolfi | null`	No	Linux distribution for base image
`dockerfile_lines`	`array[string]`	No	Additional Docker instructions
`pip_installer`	null`	No	Package installer (`auto`, `pip`, `uv`)
`ui`	null`	No	UI component definitions
`api_version`	null`	No	LangGraph API server version

Key Sub-Configurations
Config	Key Fields	Description
`AuthConfig`	`path`, `openapi`, `cache`, `disable_studio_auth`	Custom auth with OpenAPI security schemes
`HttpConfig`	`app`, `cors`, `disable_*`, `configurable_headers`, `mount_prefix`	HTTP server routes and CORS
`StoreConfig`	`index` (embed, dims, fields), `ttl`	Memory store with optional vector search
`CheckpointerConfig`	`ttl` (default_ttl, strategy), `serde`, `sweep_limit`	State checkpointing and cleanup
`WebhooksConfig`	`url` (policy), `headers`, `env_prefix`	Outbound event delivery with URL validation

Usage Examples

{
  "dependencies": ["langchain-openai", "./my_agent"],
  "graphs": {
    "my_graph": "my_agent.graph:compiled_graph"
  },
  "python_version": "3.12",
  "env": ".env",
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["content", "title"]
    }
  },
  "auth": {
    "path": "my_agent.auth:my_auth",
    "openapi": {
      "securitySchemes": {
        "ApiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "x-api-key"
        }
      },
      "security": [{"ApiKeyAuth": []}]
    }
  },
  "http": {
    "cors": {
      "allow_origins": ["https://myapp.com"],
      "allow_methods": ["GET", "POST"],
      "allow_credentials": true
    }
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "default_ttl": 60,
      "sweep_interval_minutes": 5
    }
  }
}

Related Pages

• Principle:Langchain_ai_Langgraph_Project_Configuration