Installation
-
Ensure Docker is installed (e.g.,
docker --version). -
Install the CLI:
-
Verify the install
Quick commands
For JS, use
npx @langchain/langgraph-cli <command> (or langgraphjs if installed globally).
Configuration file
To build and run a valid application, the LangGraph CLI requires a JSON configuration file that follows this schema. It contains the following properties:The LangGraph CLI defaults to using the configuration file named langgraph.json in the current directory.
- Python
- JS
Examples
- Python
- JS
Basic configuration
Install from a uv lockfile
When the project already has auv.lock, set source.kind to "uv" so image builds install the locked versions. Omit dependencies in this mode. The CLI exports requirements with uv export --frozen and installs them into the image.Single-package project (pyproject.toml and uv.lock next to langgraph.json):langgraph.json inside a member; lockfile at the workspace root):source, a "dependencies": ["."] build re-resolves packages from pyproject.toml at image build time and does not use uv.lock. Pin versions in pyproject.toml or use source.kind: "uv" when lockfile reproducibility matters.Using Wolfi base images
You can specify the Linux distribution for your base image using theimage_distro field. Valid options are debian, wolfi, bookworm, or bullseye. Wolfi is the recommended option as it provides smaller and more secure images. This is available in langgraph-cli>=0.2.11.Adding semantic search to the store
All Agent Servers come with a DB-backed BaseStore. Adding an “index” configuration to yourlanggraph.json will enable semantic search within the BaseStore of your Agent Server.The index.fields configuration determines which parts of your documents to embed:- If omitted or set to
["$"], the entire document will be embedded - To embed specific fields, use JSON path notation:
["metadata.title", "content.text"] - Documents missing specified fields will still be stored but won’t have embeddings for those fields
- You can still override which fields to embed on a specific item at
puttime using theindexparameter
Common model dimensions
openai:text-embedding-3-large: 3072openai:text-embedding-3-small: 1536openai:text-embedding-ada-002: 1536cohere:embed-english-v3.0: 1024cohere:embed-english-light-v3.0: 384cohere:embed-multilingual-v3.0: 1024cohere:embed-multilingual-light-v3.0: 384
Semantic search with a custom embedding function
If you want to use semantic search with a custom embedding function, you can pass a path to a custom embedding function:embed field in store configuration can reference a custom function that takes a list of strings and returns a list of embeddings. Example implementation:Adding custom authentication
Configuring store item Time-to-Live
You can configure default data expiration for items/memories in the BaseStore using thestore.ttl key. This determines how long items are retained after they are last accessed (with reads potentially refreshing the timer based on refresh_on_read). Note that these defaults can be overwritten on a per-call basis by modifying the corresponding arguments in get, search, etc.The ttl configuration is an object containing optional fields:refresh_on_read: Iftrue(the default), accessing an item viagetorsearchresets its expiration timer. Set tofalseto only refresh TTL on writes (put).default_ttl: The default lifespan of an item in minutes. Applies only to newly created items; existing items are not modified. If not set, items do not expire by default.sweep_interval_minutes: How frequently (in minutes) the system should run a background process to delete expired items. If not set, sweeping does not occur automatically.
Configuring checkpoint Time-to-Live
You can configure the time-to-live (TTL) for checkpoints using thecheckpointer 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:ttl: Includesstrategy,sweep_interval_minutes,default_ttl, andsweep_limit(Agent Server v0.8+), which collectively set how checkpoints expire.serde(Agent Server v0.5+) : Lets you control deserialization behavior for checkpoint payloads.
Configuring checkpointer serde
Thecheckpointer.serde object shapes deserialization:allowed_json_modulesdefines 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 totrueto allow any module to be deserialized.pickle_fallback: Whether to fall back to pickle deserialization when JSON decoding fails.
Customizing HTTP middleware and headers
Thehttp 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 throughhttp.app. -
configurable_headers/logging_headers: Each accepts an object with optionalincludesandexcludesarrays; wildcards are supported and exclusions run before inclusions. -
cors: Customize your server’s CORS (Cross-Origin Resource Sharing) configuration. Examplelanggraph.jsonfile for configuring CORS:Customizing your server’s CORS configuration will override the functionality of setting theCORS_ALLOW_ORIGINSenvironment variable.
Configuring webhooks
You can configure custom headers and URL restrictions for outbound webhook requests:Pinning API version
(Added in v0.3.7)You can pin the API version of the Agent Server by using theapi_version key. This is useful if you want to ensure that your server uses a specific version of the API.
By default, builds for Agent Servers on Cloud use the latest stable version of the server. This can be pinned by setting the api_version key to a specific version.Disabling built-in routes
You can selectively disable groups of built-in HTTP routes using boolean flags in thehttp configuration block. This is useful for production Agent Servers where you want to minimize the server’s exposed surface area.For example, to disable the system information and documentation routes:disable_meta to true disables the following routes:/— root health check/info— server version and configuration info/metrics— Prometheus and JSON metrics/docs— API documentation UI/openapi.json— OpenAPI specification
/ok health check endpoint remains available even when disable_meta is set, so orchestrators like Kubernetes can still perform liveness and readiness probes.Other route disable flags include disable_assistants, disable_runs, disable_threads, disable_store, and disable_ui. For MCP, A2A, and webhooks, see their respective guides: Disable MCP, Disable A2A, Disable webhooks.Commands
Usage- Python
- JS
The base command for the LangGraph CLI is
langgraph.dev
- Python
- JS
Run Agent Server in development mode with hot reloading and debugging capabilities. This lightweight server requires no Docker installation and is suitable for development and testing. State is persisted to a local directory.InstallationThis command requires the “inmem” extra to be installed:UsageOptions
Currently, the CLI only supports Python 3.11 or later
build
- Python
- JS
Build Agent Server Docker image.UsageOptions
*Only supported for JS Agent Servers, will have no impact on Python Agent Servers.
deploy
- Python
This command is in beta and under active development. Expect frequent updates and improvements. On LangSmith Cloud (SaaS) in AWS, local builds require
langgraph-cli 0.4.35 or later.- A LangSmith API key with access to LangSmith Agent Server.
- (Optional) Docker must be installed and the Docker daemon must be running for local builds. Not required for remote builds. Install Docker Desktop.
On LangSmith Cloud, the CLI pushes to a managed registry. Self-hosted LangSmith, and Cloud workspaces that deploy through a listener in your own cluster, push to a registry you manage with
--push-to. See Deploy from a registry you manage.langgraph build flags (--platform, -t, --pull, --no-pull, -c). For details, refer to langgraph build --help.OptionsThe Python CLI uses
--agent-server-id and --agent-server-type. It also accepts --deployment-id and --deployment-type as hidden compatibility aliases. If your installed version does not recognize the Agent Server flags, use the legacy spellings or upgrade. Check langgraph deploy --help for the flags your version supports.langgraph deploy creates a Serverless Agent Server by default (langgraph-cli>=0.4.37; earlier versions default to the legacy dev type). This version requirement describes the default type, not the availability of the Agent Server flag names. To create a Dedicated Agent Server, pass --agent-server-type dedicated. If your CLI only accepts dev and prod, upgrade it to use the serverless and dedicated values.CLI updates depend on the Agent Server’s source and the selected build mode. Local builds pushed to the managed registry require an
internal_docker source. To update an Agent Server from a registry you manage, use --push-to or --image-uri. Do not assume every Agent Server created through the UI or GitHub integration supports every CLI build mode.Deploy from a registry you manage
Self-hosted LangSmith, and LangSmith Cloud workspaces that deploy through a listener in your own cluster (the legacy hybrid model), run images from a registry you manage. Pass--push-to with a repository in that registry. The CLI builds the image, pushes it with your existing Docker credentials, and creates or updates the Agent Server from the pushed image.LANGSMITH_ENDPOINT, read from the project .env file or the environment: https://<host>/api-host for a self-hosted instance, and the matching LangSmith Cloud control plane for cloud endpoints. To override it, set the LANGGRAPH_HOST_URL environment variable to the full control plane URL, including /api-host on a self-hosted instance (for example https://langsmith.example.com/api-host).Deploy an image you’ve already pushed
If your CI/CD pipeline builds and pushes the image in a separate job from the one that deploys,--push-to does not work: it always builds (or retags a local --image) and pushes, and --image requires the image to be present in the local Docker daemon. Use --image-uri instead to deploy an image that’s already in a registry, with no build, retag, or push at all:--image-uri must include a digest (@sha256:<digest>), not a mutable tag. Kubernetes can cache images by tag, so redeploying the same tag could silently keep running the previous image. If your pipeline already captures the digest from its push step, pass it straight through; otherwise resolve it first, for example with docker buildx imagetools inspect <repository>:<tag> --format '{{json .Manifest.Digest}}' or your registry’s own CLI.Agent Servers created with --image-uri use the same external_docker source as --push-to, so either option can update an Agent Server the other one created.Choose a listener and namespace
When a workspace deploys through a listener, the control plane needs to know which listener runs a new Agent Server and which Kubernetes namespace it deploys into.On LangSmith Cloud, you do not have to pass either when there is only one possible answer. If your workspace has a single listener that serves a single namespace, the CLI uses it:--listener-id or --k8s-namespace. To find a listener’s id and namespaces ahead of time, for example to pass --listener-id from a script without hardcoding it, use deploy listeners list with --json:--push-to.Agent Servers created with --push-to use the external_docker source. An Agent Server created without --push-to cannot be switched to it; use a new --name instead.Authenticate to a private registry
If the registry you push to with--push-to or deploy from with --image-uri requires authentication to pull the image, the cluster needs a Kubernetes secret of type kubernetes.io/dockerconfigjson in the Agent Server’s namespace. Create it ahead of time (for example with kubectl create secret docker-registry), then pass its name with --image-pull-secret:--image-pull-secret to attach more than one secret. Like the listener and namespace, image pull secrets are fixed when the Agent Server is created; the CLI doesn’t support changing them on an existing Agent Server, but you can update the Agent Server’s resource_spec through the API or the LangSmith UI.deploy list
List Agent Servers.Usagedeploy listeners
[Beta] Inspect listeners available to this workspace.UsageCommands
deploy listeners list
[Beta] List listeners available to this workspace, with their cluster (compute_id) and Kubernetes namespaces.Pass a listener’s id to langgraph deploy --listener-id to deploy through it. See Choose a listener and namespace.Pass --json to get the listeners as a JSON array instead of a table, for scripting (for example, to pipe a listener’s id into --listener-id).Usagedeploy revisions
[Beta] Manage Agent Server revisions.UsageCommands
deploy revisions list
[Beta] List revisions for an Agent Server.Use deploy list to list Agent Server IDs.Usagedeploy delete
Delete an Agent Server.Use deploy list to find the Agent Server ID to delete.Usagedeploy logs
Fetch Agent Server logs. Use deploy for Agent Server runtime logs, or build for remote build logs.Usageup
- Python
- JS
Start Agent Server. For local testing, requires a LangSmith API key with access to LangSmith. Requires a license key for production use.UsageOptions
--debugger-base-url is deprecated. The CLI still accepts it as a hidden alias for --api-url, but use --api-url instead.dockerfile
- Python
- JS
Generate a Dockerfile for building an Agent Server Docker image.UsageOptionsThis generates a Dockerfile that looks similar to:
Example:
The
langgraph dockerfile command translates all the configuration in your langgraph.json file into Dockerfile commands. When using this command, you will have to re-run it whenever you update your langgraph.json file. Otherwise, your changes will not be reflected when you build or run the dockerfile.Connect these docs to your agent of choice via MCP for real-time answers.

