Skip to main content
This guide is for self-hosted LangSmith customers who have enabled Agent Server hosting on their instance. For Cloud customers, see Deploy on Cloud. For standalone Agent Servers without a control plane, see Self-host standalone servers.
This guide shows you how to deploy your applications to a self-hosted LangSmith instance using a 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.

Topology

Enabling Agent Server hosting on an existing self-hosted LangSmith instance adds a control plane, a data plane listener, and an operator that provisions Agent Servers in your cluster. The base LangSmith platform continues to handle observability, evaluation, and prompts; deployed Agent Servers send traces back to it. For details on the components added by enabling Agent Server hosting, see Enable Agent Server hosting.

Overview

Applications deployed to a self-hosted LangSmith instance with a 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:
  • Agent Server hosting enabled on your self-hosted LangSmith instance.
  • Access to the LangSmith UI with Agent Server hosting 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.

Step 1. Test locally

Before deploying, test your application locally. You can use the LangGraph CLI to run an Agent Server in development mode:
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:
Build command options include: Example with platform specification:
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 Agent Servers, view logs and metrics, and update configurations. To create a new Agent Server in the LangSmith UI:
  1. In the left-hand navigation panel, select Agent Servers.
  2. In the top-right corner, select + Agent Server.
  3. In the Agent Server 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 Agent Server settings as needed.
  4. Select Submit.
The control plane will coordinate with your data plane listener to deploy your application. After creating an Agent Server, 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 Agent Server 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 Agent Server with the same name as the Agent Server. Tracing environment variables are set automatically by the control plane.

Update an Agent Server

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 Agent Servers.
  2. Select an existing Agent Server.
  3. In the Agent Server 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.
This configuration is done at the infrastructure level, not per Agent Server. Once configured, all Agent Servers automatically inherit the registry credentials.
Configure imagePullSecrets in your LangSmith Helm chart’s values.yaml file. See the detailed steps in the Enable Agent Server hosting guide. For detailed steps on creating image pull secrets for different registry providers, refer to the Kubernetes documentation on pulling images from private registries.

Next steps