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

# Deploy with control plane

> Build Docker images and deploy applications to hybrid or self-hosted LangSmith instances using the control plane UI.

This guide shows you how to deploy your applications to [hybrid](/langsmith/hybrid) or [self-hosted](/langsmith/self-hosted) instances with a [control plane](/langsmith/control-plane). With a control plane, you build Docker images locally, push them to a registry that your Kubernetes cluster has access to, and deploy them with the [LangSmith UI](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=langsmith-deploy-with-control-plane).

<Note>
  **This guide is for deploying applications, not setting up infrastructure.**

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

  * **[Hybrid setup](/langsmith/deploy-hybrid)**: For hybrid hosting.
  * **[Enable LangSmith Deployment](/langsmith/deploy-self-hosted-full-platform)**: For self-hosted with control plane.

  If you haven't set up your infrastructure yet, start with the [Platform setup section](/langsmith/platform-setup).
</Note>

## 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](/langsmith/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](/langsmith/control-plane#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](/langsmith/data-plane) to receive application deployments:
  * [Hybrid setup](/langsmith/deploy-hybrid): Installs data plane components (listener, operator, CRDs) in your Kubernetes cluster that connect to LangChain's managed control plane.
  * [Enable LangSmith Deployment](/langsmith/deploy-self-hosted-full-platform): Enables LangSmith Deployment on your self-hosted LangSmith instance.
* Access to the [LangSmith UI](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=langsmith-deploy-with-control-plane) with LangSmith Deployment enabled.
* A container registry accessible by your Kubernetes cluster. If using a private registry that requires authentication, you must configure image pull secrets as part of your infrastructure setup. Refer to [Private registry authentication](#private-registry-authentication).

## Step 1. Test locally

Before deploying, test your application locally. You can use the [LangGraph CLI](/langsmith/cli#dev) to run an Agent server in development mode:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langgraph dev
```

For a full guide local testing, refer to the [Local server quickstart](/langsmith/local-dev-testing).

## Step 2. Build Docker image

Build a Docker image of your application using the [`langgraph build`](/langsmith/cli#build) command:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langgraph build --platform linux/amd64 -t my-image:v1.0.0
```

For full details, see the [CLI reference](/langsmith/cli#build).

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

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

## Step 4. Deploy with the control plane UI

The [control plane UI](/langsmith/control-plane#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](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=langsmith-deploy-with-control-plane):

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](#step-3-push-to-container-registry).
   * **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](/langsmith/data-plane) listener to deploy your application.

After creating a deployment, the infrastructure is [provisioned asynchronously](/langsmith/control-plane#asynchronous-deployment). 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](/langsmith/control-plane#monitoring).

<Note>
  A [LangSmith Observability tracing project](/langsmith/observability) is automatically created for each deployment with the same name as the deployment. Tracing environment variables are set automatically by the control plane.
</Note>

## Update deployment

To deploy a new version of your application, create a [new revision](/langsmith/control-plane#revisions):

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

## Private registry authentication

If your container registry requires authentication (e.g., AWS ECR, Azure ACR, GCP Artifact Registry, private Docker registry), you must configure Kubernetes image pull secrets before deploying applications. This is a one-time infrastructure configuration.

<Note>
  **This configuration is done at the infrastructure level, not per-deployment.** Once configured, all deployments automatically inherit the registry credentials.
</Note>

The configuration steps depend on your deployment type:

* **Self-hosted with control plane**: Configure `imagePullSecrets` in your LangSmith Helm chart's `values.yaml` file. See the detailed steps in the [Enable LangSmith Deployment guide](/langsmith/deploy-self-hosted-full-platform).
* **Hybrid**: Configure `imagePullSecrets` in your `langgraph-dataplane-values.yaml` file using the same format.

For detailed steps on creating image pull secrets for different registry providers, refer to the [Kubernetes documentation on pulling images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).

## Next steps

* **[Control plane](/langsmith/control-plane)**: Learn more about control plane features.
* **[Data plane](/langsmith/data-plane)**: Understand data plane architecture.
* **[Observability](/langsmith/observability)**: Monitor your deployments with automatic tracing.
* **[Studio](/langsmith/studio)**: Test and debug deployed applications.
* **[LangGraph CLI](/langsmith/cli)**: Full CLI reference documentation.

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/deploy-with-control-plane.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>