Local development & testing ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.

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.

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

Development#

Here’s the typical workflow when building applications:

flowchart LR
    A["Develop<br/><code>langgraph dev</code>"] --> B["Test Locally<br/><code>langgraph dev</code>"] --> C["Validate<br/><code>langgraph up</code>"] --> D["Deploy<br/>via UI or API"]

    style A fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A
    style B fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A
    style C fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#78350F
    style D fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#14532D

Recommended workflow#

1. Daily development: Use langgraph dev for rapid iteration.
2. Periodic validation: Test major changes with langgraph up.
3. Pre-deployment check: Run langgraph up --recreate for a fresh build.
4. 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": ["my-package@1.0.0"] (JavaScript)

    {
      "dependencies": ["."],
      "graphs": {
        "my_agent": "./my_agent/agent.py:graph"
      },
      "env": "./.env"
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="JavaScript"></span>
```json
    {
      "dependencies": ["."],
      "graphs": {
        "my_agent": "./my_agent/agent.js:graph"
      },
      "env": "./.env"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Package dependency files

These files define **what** packages your application needs:

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Python"></span>
**pyproject.toml example:**

```toml
    [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"
      }
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Dependency resolution process

When you run [`langgraph up`](/langsmith/cli#up), the CLI follows these steps to install your application's dependencies:

1. [`langgraph.json`](/langsmith/application-structure#configuration-file) tells the CLI **where** to look for your application code. The `dependencies: ["."]` field points to the current directory.
2. **Find package configuration**: The CLI looks in that directory for a package configuration file ([`pyproject.toml`](/langsmith/setup-pyproject), [`requirements.txt`](/langsmith/setup-app-requirements-txt), or [`package.json`](/langsmith/setup-javascript)).
3. **Read dependencies list**: The CLI reads the list of packages from the configuration file.
4. **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](/langsmith/cli#configuration-file).

### Troubleshooting

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

```json
{
  "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.

Related resources#

• 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.