diff --git a/src/langsmith/cli.mdx b/src/langsmith/cli.mdx index 57a3e6f277..b88ee03e52 100644 --- a/src/langsmith/cli.mdx +++ b/src/langsmith/cli.mdx @@ -14,9 +14,6 @@ sidebarTitle: LangGraph CLI ```bash [Python (pip)] pip install langgraph-cli ``` - ```bash Homebrew - brew install langgraph-cli - ``` ```bash JavaScript # Use latest on demand npx @langchain/langgraph-cli @@ -50,9 +47,9 @@ For JS, use `npx @langchain/langgraph-cli ` (or `langgraphjs` if instal ## Configuration file -The LangGraph CLI requires a JSON configuration file that follows this [schema](https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json). It contains the following properties: +To build and run a valid application, the LangGraph CLI requires a JSON configuration file that follows this [schema](https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json). It contains the following properties: -The LangGraph CLI defaults to using the configuration file langgraph.json in the current directory. +The LangGraph CLI defaults to using the configuration file named langgraph.json in the current directory. @@ -72,8 +69,8 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema]( | `pip_installer` | _(Added in v0.3)_ Optional. Python package installer selector. It can be set to `"auto"`, `"pip"`, or `"uv"`. From version 0.3 onward the default strategy is to run `uv pip`, which typically delivers faster builds while remaining a drop-in replacement. In the uncommon situation where `uv` cannot handle your dependency graph or the structure of your `pyproject.toml`, specify `"pip"` here to revert to the earlier behaviour. | | `keep_pkg_tools` | _(Added in v0.3.4)_ Optional. Control whether to retain Python packaging tools (`pip`, `setuptools`, `wheel`) in the final image. Accepted values:
  • true : Keep all three tools (skip uninstall).
  • false / omitted : Uninstall all three tools (default behaviour).
  • list[str] : Names of tools to retain. Each value must be one of "pip", "setuptools", "wheel".
. By default, all three tools are uninstalled. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | - | `checkpointer` | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys:
  • `strategy`: How to handle expired checkpoints (e.g., `"delete"`).
  • `sweep_interval_minutes`: How often to check for expired checkpoints (integer).
  • `default_ttl`: Default time-to-live for checkpoints in **minutes** (integer); applied to newly created checkpoints/threads only (existing data is unchanged). Defines how long checkpoints are kept before the specified strategy is applied.
| - | `http` | HTTP server configuration with the following fields:
  • `app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).
  • `cors`: CORS configuration with fields for `allow_origins`, `allow_methods`, `allow_headers`, etc.
  • `configurable_headers`: Define which request headers to exclude or include as a run's configurable values.
  • `disable_assistants`: Disable `/assistants` routes
  • `disable_mcp`: Disable `/mcp` routes
  • `disable_meta`: Disable `/ok`, `/info`, `/metrics`, and `/docs` routes
  • `disable_runs`: Disable `/runs` routes
  • `disable_store`: Disable `/store` routes
  • `disable_threads`: Disable `/threads` routes
  • `disable_ui`: Disable `/ui` routes
  • `disable_webhooks`: Disable webhooks calls on run completion in all routes
  • `mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api")
| + | `checkpointer` | Configuration for the checkpointer. Supports:
  • `ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.
  • `serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.
| + | `http` | HTTP server configuration with the following fields:
  • `app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).
  • `cors`: CORS configuration with fields such as `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, and `max_age`.
  • `configurable_headers`: Define which request headers to expose as configurable values via `includes` / `excludes` patterns.
  • `logging_headers`: Mirror of `configurable_headers` for excluding sensitive headers from logs.
  • `middleware_order`: Choose how custom middleware and auth interact. `auth_first` runs authentication hooks before custom middleware, while `middleware_first` (default) runs your middleware first.
  • `enable_custom_route_auth`: Apply auth checks to routes added through `app`.
  • `disable_assistants`, `disable_mcp`, `disable_meta`, `disable_runs`, `disable_store`, `disable_threads`, `disable_ui`, `disable_webhooks`: Disable built-in routes or hooks.
  • `mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api").
| | `api_version` | _(Added in v0.3.7)_ Which semantic version of the LangGraph API server to use (e.g., `"0.3"`). Defaults to latest. Check the server [changelog](/langsmith/langgraph-server-changelog) for details on each release. | @@ -84,7 +81,8 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema]( | `store` | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields:
  • `index` (optional): Configuration for semantic search indexing with fields `embed`, `dims`, and optional `fields`.
  • `ttl` (optional): Configuration for item expiration. An object with optional fields: `refresh_on_read` (boolean, defaults to `true`), `default_ttl` (float, lifespan in **minutes**; applied to newly created items only; existing items are unchanged; defaults to no expiration), and `sweep_interval_minutes` (integer, how often to check for expired items, defaults to no sweeping).
| | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | - | `checkpointer` | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys:
  • `strategy`: How to handle expired checkpoints (e.g., `"delete"`).
  • `sweep_interval_minutes`: How often to check for expired checkpoints (integer).
  • `default_ttl`: Default time-to-live for checkpoints in **minutes** (integer); applied to newly created checkpoints/threads only (existing data is unchanged). Defines how long checkpoints are kept before the specified strategy is applied.
| + | `checkpointer` | Configuration for the checkpointer. Supports:
  • `ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.
  • `serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.
| + | `http` | HTTP server configuration mirroring the Python options:
  • `cors` with `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, `max_age`.
  • `configurable_headers` and `logging_headers` pattern lists.
  • `middleware_order` (`auth_first` or `middleware_first`).
  • `enable_custom_route_auth` plus the same boolean route toggles as above.
| | `api_version` | _(Added in v0.3.7)_ Which semantic version of the LangGraph API server to use (e.g., `"0.3"`). Defaults to latest. Check the server [changelog](/langsmith/langgraph-server-changelog) for details on each release. | @@ -249,11 +247,10 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema]( #### Configuring checkpoint Time-to-Live - You can configure the time-to-live (TTL) for checkpoints using the `checkpointer` key. This determines how long checkpoint data is retained before being automatically handled according to the specified strategy (e.g., deletion). The `ttl` configuration is an object containing: + You can configure the time-to-live (TTL) for checkpoints using the `checkpointer` key. This determines how long checkpoint data is retained before being automatically handled according to the specified strategy (e.g., deletion). Two optional sub-objects are supported: - * `strategy`: The action to take on expired checkpoints (currently `"delete"` is the only accepted option). - * `sweep_interval_minutes`: How frequently (in minutes) the system checks for expired checkpoints. - * `default_ttl`: The default lifespan of a checkpoint in **minutes**. Applies only to checkpoints/threads created after deployment; existing data is not modified. + * `ttl`: Includes `strategy`, `sweep_interval_minutes`, and `default_ttl`, which collectively set how checkpoints expire. + * `serde` _(LangGraph server 0.5+)_ : Lets you control deserialization behavior for checkpoint payloads. Here's an example setting a default TTL of 30 days (43200 minutes): @@ -276,6 +273,34 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema]( In this example, checkpoints older than 30 days will be deleted, and the check runs every 10 minutes. + #### Configuring checkpointer serde + + The `checkpointer.serde` object shapes deserialization: + + * `allowed_json_modules` defines an allow list for custom Python objects you want the server to be able to deserialize from payloads saved in "json" mode. This is a list of `[path, to, module, file, symbol]` sequences. If omitted, only LangChain-safe defaults are allowed. You can unsafely set to `true` to allow any module to be deserialized. + * `pickle_fallback`: Whether to fall back to pickle deserialization when JSON decoding fails. + + ```json + { + "checkpointer": { + "serde": { + "allowed_json_modules": [ + ["my_agent", "auth", "SessionState"] + ] + } + } + } + ``` + + #### Customizing HTTP middleware and headers + + The `http` block lets you fine-tune request handling: + + * `middleware_order`: Choose `"auth_first"` to run authentication before your middleware, or `"middleware_first"` (default) to invert that order. + * `enable_custom_route_auth`: Extend authentication to routes you mount through `http.app`. + * `configurable_headers` / `logging_headers`: Each accepts an object with optional `includes` and `excludes` arrays; wildcards are supported and exclusions run before inclusions. + * `cors`: In addition to `allow_origins`, `allow_methods`, and `allow_headers`, you can set `allow_credentials`, `allow_origin_regex`, `expose_headers`, and `max_age` for detailed browser control. + #### Pinning API version