Deploy with control plane

This guide shows you how to deploy your applications to hybrid or self-hosted instances with a control plane. With a control plane, you build Docker images locally and deploy them with the LangSmith UI.

This guide is for deploying applications, not setting up infrastructure.

Before using this guide, you must have already completed infrastructure setup:

• Hybrid setup: For hybrid hosting.
• Self-hosted with deployment setup: For self-hosted with control plane.

If you haven’t set up your infrastructure yet, start with the Hosting section.

Overview

Applications deployed to hybrid or self-hosted LangSmith instances with control plane use Docker images. In this guide, the application deployment workflow is:

1. Test your application locally using langgraph dev or Studio.
2. Build a Docker image using the langgraph build command.
3. Push the image to a container registry accessible by your infrastructure.
4. Deploy from the control plane UI by specifying the image URL.

Prerequisites

Before completing this guide, you’ll need the following:

• Completed infrastructure setup to enable your data plane to receive application deployments:
  • Hybrid setup: Installs data plane components (listener, operator, CRDs) in your Kubernetes cluster that connect to LangChain’s managed control plane.
  • Self-hosted with deployment setup: Enables deployment management on your self-hosted LangSmith instance.
• Access to the LangSmith UI with deployment management enabled.
• A container registry accessible by your Kubernetes cluster.

Step 1. Test locally

Before deploying, test your application locally. You can use the LangGraph CLI to run a LangGraph server in development mode:

langgraph dev

For a full guide local testing, refer to the Local server quickstart.

Step 2. Build Docker image

Build a Docker image of your application using the langgraph build command:

langgraph build -t my-image

Build command options include:

Option	Default	Description
-t, --tag TEXT	Required	Tag for the Docker image
--platform TEXT		Target platform(s) to build for (e.g., linux/amd64,linux/arm64)
--pull / --no-pull	--pull	Build with latest remote Docker image
-c, --config FILE	langgraph.json	Path to configuration file

Example with platform specification:

langgraph build --platform linux/amd64 -t my-image:v1.0.0

For full details, see the CLI reference.

Step 3. Push to container registry

Push your image to a container registry accessible by your Kubernetes cluster. The specific commands depend on your registry provider.

Tag your images with version information (e.g., my-registry.com/my-app:v1.0.0) to make rollbacks easier.

Step 4. Deploy with the control plane UI

The control plane UI allows you to create and manage deployments, view logs and metrics, and update configurations. To create a new deployment in the LangSmith UI:

1. In the left-hand navigation panel, select Deployments.
2. In the top-right corner, select + New Deployment.
3. In the deployment configuration panel, provide:
   • Image URL: The full image URL you pushed in Step 3.
   • Listener/Compute ID: Select the listener configured for your infrastructure.
   • Namespace: The Kubernetes namespace to deploy to.
   • Environment variables: Any required configuration (API keys, etc.).
   • Other deployment settings as needed.
4. Select Submit.

The control plane will coordinate with your data plane listener to deploy your application.

After creating a deployment, the infrastructure is provisioned asynchronously. Deployment can take up to several minutes, with initial deployments taking longer due to database creation.

From the control plane UI, you can view build logs, server logs, and deployment metrics including CPU/memory usage, replicas, and API performance. For more details, refer to the control plane monitoring documentation.

A LangSmith Observability tracing project is automatically created for each deployment with the same name as the deployment. Tracing environment variables are set automatically by the control plane.

Update deployment

To deploy a new version of your application, create a new revision:

Starting from the LangSmith UI:

1. In the left-hand navigation panel, select Deployments.
2. Select an existing deployment.
3. In the Deployment view, select + New Revision in the top-right corner.
4. Update the configuration:
   • Update the Image URL to your new image version.
   • Update environment variables if needed.
   • Adjust other settings as needed.
5. Select Submit.

Next steps

• Control plane: Learn more about control plane features.
• Data plane: Understand data plane architecture.
• Observability: Monitor your deployments with automatic tracing.
• Studio: Test and debug deployed applications.
• LangGraph CLI: Full CLI reference documentation.

---

Edit the source of this page on GitHub.

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