Local development & testing

This is a conceptual guide for developing and testing Agent Server applications locally. Learn about the local development tools available, when to use each one, and how they fit into your workflow from initial development through to deploying Agent Server in production. The LangGraph CLI provides two commands for local development, each optimized for different stages of your workflow:

langgraph dev: A lightweight development server for rapid iteration.
langgraph up: A production-like testing environment for validation.

Feature	`langgraph dev`	`langgraph up`
Docker required	No	Yes
Installation	`pip install langgraph-cli[inmem]`	`pip install langgraph-cli`
Primary use case	Rapid development & testing	Production-like validation
State persistence	In-memory & pickled to local directory	PostgreSQL
Hot reloading	Yes (default)	Optional (`--watch` flag)
Default port	`2024`	`8123`
Resource usage	Lightweight	Heavier (build and run separate docker containers for the server, PostgreSQL, and Redis)
IDE Debugging	Built-in DAP support	Regular container debugging
Custom auth	Yes	Yes (with license key)

For full reference details, refer to the LangGraph CLI reference page.

Development

Here’s the typical workflow when building applications:

Stage	Tool	Purpose
Develop & Test Locally	`langgraph dev`	Write and iterate on your graph with hot reloading
Validate	`langgraph up`	Test production-like behavior with full stack
Deploy	LangSmith UI or Control Plane API	Deploy to production with confidence

Recommended workflow

Daily development: Use langgraph dev for rapid iteration.
Periodic validation: Test major changes with langgraph up.
Pre-deployment check: Run langgraph up --recreate for a fresh build.
Deploy: Push to production via the LangSmith UI or Control Plane API.

`langgraph dev`

The langgraph dev command runs a lightweight server directly in your environment, designed for speed and convenience during active development. The key features include:

No Docker required: Runs directly in your environment.
Hot reloading: Automatically reloads when you change code.
Fast startup: Ready in seconds.
Built-in Debug Adapter Protocol support: Attach your IDE debugger to the server for line-level breakpoints & debugging.
Local storage: State persisted to local directory.

The dev server is tested with the same integration test suite as production to ensure its behavior is the same during development while using minimal resources.

Get started

# Install with inmem extra
pip install -U "langgraph-cli[inmem]"

# Start dev server
langgraph dev

Your server starts at http://localhost:2024 with hot reloading enabled by default.

Use cases

Use langgraph dev as your primary development tool for:

Daily feature development: Make changes to your code and the server automatically reloads. Test immediately without rebuilding containers—perfect for fast iteration cycles.
Quick prototyping and experiments: Spin up a server in seconds to test ideas without Docker setup overhead.
Environments without Docker: In CI/CD pipelines or lightweight VMs where Docker isn’t available:
```
langgraph dev --no-browser
```
Debugger attachment: Use --debug-port to attach your IDE debugger for step-through debugging during development.

`langgraph up`

The langgraph up command orchestrates a full Docker-based stack that mirrors production infrastructure, helping catch deployment issues before production. The key features include:

Verify build & dependencies: Tests your build process and dependencies.
Isolated networking: Realistic container networking.
Production validation: Verifies deployment readiness.

Get started

# Ensure Docker is running
docker ps

# Start production-like stack
langgraph up

Your server starts at http://localhost:8123 with full persistent storage.

Use cases

Use langgraph up for validation and production-readiness testing:

Pre-deployment validation: Before deploying to production, you can run a final check with a fresh build to ensure your dependencies are all correctly specified.
```
langgraph up --recreate
```
This catches issues related to dependency resolution in containers and any other build process problems.
Major feature validation: After implementing significant changes, test with the full production stack periodically to ensure everything works in a containerized environment.
Docker troubleshooting: When debugging container-specific issues, networking problems, or environment variable configurations that only appear in production.

Pre-deployment checklist

Before deploying an application, verify the following with langgraph up:

All dependencies install correctly in the container.
Application starts without errors.
Graph executes successfully.
All environment variables work correctly.
Authentication/authorization works as expected.

Dependencies configuration

Both langgraph dev and langgraph up read your application’s dependencies from your configuration files, but they run in different environments:

langgraph dev runs your code directly in your local environment (Python or Node.js) without Docker.
langgraph up builds a Docker container and runs your code inside that isolated container.

Properly configuring your dependencies ensures both commands work correctly and that what you test locally matches what gets deployed to production.

`langgraph.json` file

The dependencies field tells the CLI where to find your application code. The dependencies field can point to:

A directory with package config (containing pyproject.toml, setup.py, requirements.txt, or package.json)
A specific subdirectory: "dependencies": ["./my_agent"]
A specific package: "dependencies": ["my-package==1.0.0"] (Python) or "dependencies": ["[email protected]"] (JavaScript)

Python
JavaScript

{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./my_agent/agent.py:graph"
  },
  "env": "./.env"
}

{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./my_agent/agent.js:graph"
  },
  "env": "./.env"
}

Package dependency files

These files define what packages your application needs:

Python
JavaScript

pyproject.toml example:

[project]
name = "my-agent"
version = "0.1.0"
dependencies = [
    "langchain-openai",
    "langchain-anthropic",
    "langgraph",
]

requirements.txt example:

langchain-openai
langchain-anthropic
langgraph

package.json example:

{
  "name": "my-agent",
  "version": "1.0.0",
  "dependencies": {
    "@langchain/openai": "^0.3.0",
    "@langchain/anthropic": "^0.3.0",
    "@langchain/langgraph": "^0.2.0"
  }
}

Dependency resolution process

When you run langgraph up, the CLI follows these steps to install your application’s dependencies:

langgraph.json tells the CLI where to look for your application code. The dependencies: ["."] field points to the current directory.
Find package configuration: The CLI looks in that directory for a package configuration file (pyproject.toml, requirements.txt, or package.json).
Read dependencies list: The CLI reads the list of packages from the configuration file.
Install packages: The CLI installs all the packages using the appropriate package manager for your language (uv or pip for Python, npm for JavaScript).

This two-file approach separates concerns: langgraph.json handles application structure and location, while the package configuration file handles language-specific package dependencies. For more information on the installer, refer to CLI configuration file.

Troubleshooting

If you encounter issues with dependency installation, try switching to pip:

{
  "dependencies": ["."],
  "pip_installer": "pip"
}

Then rebuild:

langgraph up --recreate

Debug your local Docker setup

Production deployment might succeed even when langgraph up fails on your local machine. This happens because production uses managed infrastructure while langgraph up runs the full stack locally on your computer. The following are common local environment issues that don’t affect production.

Docker configuration issues

langgraph up requires Docker locally:

# Check if Docker is running
docker ps

Cloud deployments don’t use your local Docker. Solution: Install Docker, or use langgraph dev for local testing.

Port conflicts

langgraph up uses ports 8123, 5432, and 6379 that might be occupied:

# Check for conflicts
lsof -i :8123  # API server
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis

Solution: Stop conflicting services or use the --port flag.

Resource constraints

langgraph up requires more RAM and disk for:

PostgreSQL container
Redis container
API server container

Solution: Free up resources or use langgraph dev.

Network configuration

VPN connections, firewall rules, or corporate proxy settings can affect local Docker networking. Solution: Test with langgraph dev or temporarily disable VPN/firewall to isolate the issue.

CLI Reference: Detailed documentation for all CLI commands
Application Structure: How to structure your LangGraph application
Local Development: Getting started with local development
Troubleshooting: Common issues and solutions
Setting up with pyproject.toml: Configure Python dependencies
Setting up with requirements.txt: Alternative dependency configuration

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Configure app for deployment

Deployment guides

App development

Studio

Auth & access control

Server customization

Development

Recommended workflow

`langgraph dev`

Get started

Use cases

`langgraph up`

Get started

Use cases

Pre-deployment checklist

Dependencies configuration

`langgraph.json` file

Package dependency files

Dependency resolution process

Troubleshooting

Debug your local Docker setup

Docker configuration issues

Port conflicts

Resource constraints

Network configuration

Configure app for deployment

Deployment guides

App development

Studio

Auth & access control

Server customization

​Development

​Recommended workflow

​langgraph dev

​Get started

​Use cases

​langgraph up

​Get started

​Use cases

​Pre-deployment checklist

​Dependencies configuration

​langgraph.json file

​Package dependency files

​Dependency resolution process

​Troubleshooting

​Debug your local Docker setup

​Docker configuration issues

​Port conflicts

​Resource constraints

​Network configuration

​Related resources

Development

Recommended workflow

`langgraph dev`

Get started

Use cases

`langgraph up`

Get started

Use cases

Pre-deployment checklist

Dependencies configuration

`langgraph.json` file

Package dependency files

Dependency resolution process

Troubleshooting

Debug your local Docker setup

Docker configuration issues

Port conflicts

Resource constraints

Network configuration

Related resources