Update cli config (#1271)

hinthornw · Copilot · web-flow · commit 6b3b9e361b0d · 2025-11-04T06:35:45.000-08:00
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git 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 <command>` (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:
 
-<Note>The LangGraph CLI defaults to using the configuration file <strong>langgraph.json</strong> in the current directory.</Note>
+<Note>The LangGraph CLI defaults to using the configuration file named <strong>langgraph.json</strong> in the current directory.</Note>
 
 <Tabs>
     <Tab title="Python">
@@ -72,8 +69,8 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](
         | <span style={{ whiteSpace: "nowrap" }}>`pip_installer`</span> | _(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. |
         | <span style={{ whiteSpace: "nowrap" }}>`keep_pkg_tools`</span> | _(Added in v0.3.4)_ Optional. Control whether to retain Python packaging tools (`pip`, `setuptools`, `wheel`) in the final image. Accepted values: <ul><li><code>true</code> : Keep all three tools (skip uninstall).</li><li><code>false</code> / omitted : Uninstall all three tools (default behaviour).</li><li><code>list[str]</code> : Names of tools <strong>to retain</strong>. Each value must be one of "pip", "setuptools", "wheel".</li></ul>. By default, all three tools are uninstalled. |
         | <span style={{ whiteSpace: "nowrap" }}>`dockerfile_lines`</span> | Array of additional lines to add to Dockerfile following the import from parent image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-        | <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span>   | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys: <ul><li>`strategy`: How to handle expired checkpoints (e.g., `"delete"`).</li><li>`sweep_interval_minutes`: How often to check for expired checkpoints (integer).</li><li>`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.</li></ul> |
-        | <span style={{ whiteSpace: "nowrap" }}>`http`</span>            | HTTP server configuration with the following fields: <ul><li>`app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).</li><li>`cors`: CORS configuration with fields for `allow_origins`, `allow_methods`, `allow_headers`, etc.</li><li>`configurable_headers`: Define which request headers to exclude or include as a run's configurable values.</li><li>`disable_assistants`: Disable `/assistants` routes</li><li>`disable_mcp`: Disable `/mcp` routes</li><li>`disable_meta`: Disable `/ok`, `/info`, `/metrics`, and `/docs` routes</li><li>`disable_runs`: Disable `/runs` routes</li><li>`disable_store`: Disable `/store` routes</li><li>`disable_threads`: Disable `/threads` routes</li><li>`disable_ui`: Disable `/ui` routes</li><li>`disable_webhooks`: Disable webhooks calls on run completion in all routes</li><li>`mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api")</li></ul> |
+        | <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span>   | Configuration for the checkpointer. Supports: <ul><li>`ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.</li><li>`serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.</li></ul> |
+        | <span style={{ whiteSpace: "nowrap" }}>`http`</span>            | HTTP server configuration with the following fields: <ul><li>`app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).</li><li>`cors`: CORS configuration with fields such as `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, and `max_age`.</li><li>`configurable_headers`: Define which request headers to expose as configurable values via `includes` / `excludes` patterns.</li><li>`logging_headers`: Mirror of `configurable_headers` for excluding sensitive headers from logs.</li><li>`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.</li><li>`enable_custom_route_auth`: Apply auth checks to routes added through `app`.</li><li>`disable_assistants`, `disable_mcp`, `disable_meta`, `disable_runs`, `disable_store`, `disable_threads`, `disable_ui`, `disable_webhooks`: Disable built-in routes or hooks.</li><li>`mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api").</li></ul> |
         | <span style={{ whiteSpace: "nowrap" }}>`api_version`</span>     | _(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. |
     </Tab>
     <Tab title="JS">
@@ -84,7 +81,8 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](
         | <span style={{ whiteSpace: "nowrap" }}>`store`</span>            | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields: <ul><li>`index` (optional): Configuration for semantic search indexing with fields `embed`, `dims`, and optional `fields`.</li><li>`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).</li></ul> |
         | <span style={{ whiteSpace: "nowrap" }}>`node_version`</span>     | Specify `node_version: 20` to use LangGraph.js.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
         | <span style={{ whiteSpace: "nowrap" }}>`dockerfile_lines`</span> | Array of additional lines to add to Dockerfile following the import from parent image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-        | <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span>   | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys: <ul><li>`strategy`: How to handle expired checkpoints (e.g., `"delete"`).</li><li>`sweep_interval_minutes`: How often to check for expired checkpoints (integer).</li><li>`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.</li></ul> |
+        | <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span>   | Configuration for the checkpointer. Supports: <ul><li>`ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.</li><li>`serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.</li></ul> |
+        | <span style={{ whiteSpace: "nowrap" }}>`http`</span>            | HTTP server configuration mirroring the Python options: <ul><li>`cors` with `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, `max_age`.</li><li>`configurable_headers` and `logging_headers` pattern lists.</li><li>`middleware_order` (`auth_first` or `middleware_first`).</li><li>`enable_custom_route_auth` plus the same boolean route toggles as above.</li></ul> |
         | <span style={{ whiteSpace: "nowrap" }}>`api_version`</span>     | _(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. |
     </Tab>
 </Tabs>
@@ -249,11 +247,10 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](
         <a id="ttl"></a>
     #### 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.
+
         <a id="api-version"></a>
     #### Pinning API version
 
