Principle:Langchain ai Langgraph Development Server
| Property | Value |
|---|---|
| Concept | Running a Local Development Server with Hot-Reloading for Iterative Graph Development |
| Category | Development Workflow |
| Scope | CLI Deployment Workflow |
| Related Workflow | CLI_Deployment |
Overview
The Development Server in LangGraph provides a lightweight, in-process API server for local graph development and testing. Unlike the Docker-based deployment commands (`langgraph build` and `langgraph up`), the development server runs directly in the developer's Python environment without Docker, enabling rapid iteration through automatic code reloading, integrated debugging support, and direct connectivity to LangGraph Studio for visual graph inspection.
Description
Development Workflow
The development server is designed for the inner loop of graph development:
- A developer writes or modifies graph code.
- The development server detects the change and automatically reloads.
- The developer tests the graph via the local API, LangGraph Studio, or programmatic clients.
- The cycle repeats without requiring Docker rebuilds or container restarts.
This tight feedback loop significantly accelerates development compared to the full Docker-based deployment workflow.
In-Memory Execution
The development server runs the LangGraph API server in-memory within the developer's Python process. It imports the `langgraph_api` package (installed via `pip install "langgraph-cli[inmem]"`) and calls its `run_server` function directly. This approach:
- Eliminates Docker build time entirely.
- Shares the developer's local Python environment and installed packages.
- Enables direct access to local files and environment variables.
Hot Reloading
By default, the development server monitors the project files for changes and automatically restarts when modifications are detected. This is controlled by the `--no-reload` flag. The reload mechanism watches the configuration file and all local dependency directories specified in the `dependencies` list.
Debugging Support
The development server supports remote debugging via the `debugpy` protocol:
- `--debug-port`: Specifies the port for the debug server to listen on.
- `--wait-for-client`: Pauses server startup until a debugger client connects.
This enables IDE-based debugging (e.g., VS Code, PyCharm) with breakpoints, step-through execution, and variable inspection directly in the running graph code.
LangGraph Studio Integration
Upon startup, the development server can automatically open LangGraph Studio in the browser (unless `--no-browser` is specified). Studio provides a visual interface for:
- Inspecting graph topology and node connections.
- Sending test inputs and observing graph execution.
- Viewing thread state and checkpoint history.
- Interacting with human-in-the-loop interrupts.
The `--studio-url` option allows connecting to a custom Studio instance, and the `--tunnel` flag exposes the local server via a Cloudflare tunnel for remote frontend access.
Configuration Loading
The development server reads the same `langgraph.json` configuration file used by the Docker-based commands. It extracts:
- Graph definitions from the `graphs` dictionary.
- Environment variables from the `env` field.
- Store, auth, HTTP, UI, and webhook configurations.
Local dependency directories are added to `sys.path` so that graph modules can be imported directly without pip installation.
Usage
Basic Development Server
# Start the development server with default settings
langgraph dev
# Start on a custom port
langgraph dev --port 8000
# Start with a specific config file
langgraph dev --config my_config.json
Debugging Session
# Enable remote debugging on port 5678
langgraph dev --debug-port 5678
# Wait for debugger to attach before starting
langgraph dev --debug-port 5678 --wait-for-client
Advanced Options
# Disable hot reloading
langgraph dev --no-reload
# Expose via tunnel for remote access
langgraph dev --tunnel
# Bind to all interfaces (for container/VM access)
langgraph dev --host 0.0.0.0
# Skip opening the browser
langgraph dev --no-browser
Theoretical Basis
Hot Reloading
Hot reloading (or "live reload") is a development technique where the running application is automatically restarted or updated when source code changes are detected. This eliminates the manual restart cycle and provides near-instant feedback, which is critical for iterative development of complex stateful systems like multi-agent graphs.
Local Debugging
The debug protocol integration follows the Debug Adapter Protocol (DAP) standard via `debugpy`. This enables language-agnostic debugging tools to inspect the running server's state, set breakpoints in graph node functions, and step through the execution of individual graph transitions.
Development vs. Production Parity
While the development server uses the same configuration file as production deployments, it intentionally differs in execution model (in-process vs. Docker) to optimize for developer experience. The shared configuration ensures that the graph definitions, environment variables, and feature flags tested locally match what will be deployed. The gap is bridged by the `langgraph build` and `langgraph up` commands, which produce production-equivalent Docker images.
LangGraph Studio as a Development Tool
LangGraph Studio provides a graphical development environment that complements the CLI-based workflow. By connecting to the local development server's API, Studio enables visual graph exploration and testing without requiring any additional infrastructure. This is particularly valuable for complex multi-agent systems where understanding the flow of control between nodes is essential.