Enable LangSmith Deployment, Fleet, Insights, and Polly

Enable LangSmith Deployment, Fleet, Insights, and Polly on a self-hosted LangSmith instance.

In addition to the base LangSmith platform, you can enable the following features:

• LangSmith Deployment adds a control plane and data plane that let you deploy, scale, and manage agents and applications directly through the LangSmith UI.

  If you don’t need the full UI-based setup, see the Standalone Server for a lightweight alternative.

• Fleet allows you to create, deploy, and manage AI agents directly within LangSmith with no code.

• Insights provides AI-powered analysis of your traces and application data within LangSmith.

• Polly provides an AI assistant embedded in your LangSmith workspace to help you analyze traces, threads, prompts, and experiment results.

These features require an Enterprise plan. Get a demo to learn more.

Prerequisites

1. Install the base LangSmith platform

   Follow the Kubernetes installation guide to install the base LangSmith platform before continuing.

2. Install KEDA

   Run the following commands to install KEDA on your cluster:

   helm repo add kedacore https://kedacore.github.io/charts
   helm upgrade --install keda kedacore/keda --namespace keda --create-namespace
   

   KEDA automatically scales the deployment system based on queue size.

3. Configure an ingress

   Configure an ingress, gateway, or Istio for your LangSmith instance. All agents will be deployed as Kubernetes services behind this ingress. See Set up an ingress. You must provide a hostname in your langsmith_config.yaml.

4. Verify cluster capacity

   Ensure your cluster has available capacity for multiple deployments. A cluster autoscaler is recommended.

5. Verify storage

   Ensure a valid dynamic PV provisioner or PVs are available on your cluster.

   kubectl get storageclass
   

   At least one StorageClass should have a PROVISIONER value (not kubernetes.io/no-provisioner) and be marked (default), or you must configure one before proceeding.

6. Verify egress

   Ensure egress to https://beacon.langchain.com is available. See the egress documentation.

Enable LangSmith Deployment

Components

Enabling LangSmith Deployment provisions the following resources in your cluster:

• listener: Listens to the control plane for changes to your deployments and creates or updates downstream CRDs.
• LangGraphPlatform CRD: Manages instances of LangSmith Deployment.
• operator: Handles changes to your LangSmith CRDs.
• host-backend: The control plane.

Enable the feature

To enable LangSmith Deployment, update your langsmith_config.yaml:

1. Enable deployment in your config

   In your langsmith_config.yaml, enable the deployment option. You must also have a valid ingress configured.

   config:
     deployment:
       enabled: true
   

   As of v0.12.0, the langgraphPlatform option is deprecated. Use config.deployment for any version after v0.12.0.

2. (Optional) Configure image mirroring

   If you need to mirror images to a private registry, configure the hostBackendImage and operatorImage options in your langsmith_config.yaml. Use the image tags specified in the latest LangSmith Helm chart release.

   hostBackendImage:
     repository: "docker.io/langchain/hosted-langserve-backend"
     pullPolicy: IfNotPresent
   operatorImage:
     repository: "docker.io/langchain/langgraph-operator"
     pullPolicy: IfNotPresent
   
3. (Optional) Configure base agent templates

   Override the base agent templates in values.yaml if you need to customize how the operator creates agent Kubernetes resources. The most common use case is adding imagePullSecrets to authenticate with a private container registry. See Configure authentication for private registries for details.

4. Apply the changes

   Run the following command to apply the changes. This command is used throughout this guide whenever you are asked to apply changes. Replace <version> and <namespace> with your values:

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

   Verify that the new pods are running before continuing:

   kubectl get pods -n <namespace>
   

   Your instance is now ready to create deployments.

Enable Fleet, Insights, and Polly

Fleet, Insights, and Polly require LangSmith Deployment to be enabled first.

Fleet requires LangSmith Self-Hosted v0.13 or later.

These features share two requirements: the agentBootstrap component and a Fernet encryption key for each feature. You can enable all three features in a single Helm configuration.

Components

Enabling these features provisions the following components in your cluster:

• agentBootstrap: Job that deploys the LangSmith Deployment agent required by Fleet, Insights, and Polly.
• agentBuilder: The Fleet agent, consisting of:
  • toolServer: Provides MCP tool execution for agents.
  • triggerServer: Handles webhooks and scheduled triggers.
  • agent: The main agent where all Fleet assistants are created.
• insightsAgent: The main agent that handles Insights generation.
• polly (agent): The main agent that powers Polly across LangSmith (observability, threads, prompt playground, experiments).

Generate encryption keys

Each feature uses its own Fernet encryption key to encrypt feature-specific secrets such as credentials and tokens. Separate keys allow independent rotation and limit exposure if a key is compromised. Generate one key per feature using Python:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

We recommend storing each key in a predefined Kubernetes secret rather than setting them directly in your config file. See Use an existing secret for the relevant parameters: agent_builder_encryption_key, insights_encryption_key, and polly_encryption_key.

Enable features

1. Add the configuration to your langsmith_config.yaml

   Using Kubernetes secrets (recommended)

   Reference your existing secret by name. The chart reads agent_builder_encryption_key, insights_encryption_key, and polly_encryption_key from it automatically.

   backend:
     agentBootstrap:
       enabled: true
   
   config:
     existingSecretName: "<your-secret-name>"
     agentBuilder:
       enabled: true
     insights:
       enabled: true
     polly:
       enabled: true
   
   agentBuilderToolServer:
     enabled: true
   
   agentBuilderTriggerServer:
     enabled: true
   

   Using inline values

   Set the encryption keys directly in your config file. Avoid committing this file to version control.

   backend:
     agentBootstrap:
       enabled: true
   
   config:
     agentBuilder:
       enabled: true
       encryptionKey: "<fleet-encryption-key>"
     insights:
       enabled: true
       encryptionKey: "<insights-encryption-key>"
     polly:
       enabled: true
       encryptionKey: "<polly-encryption-key>"
   
   agentBuilderToolServer:
     enabled: true
   
   agentBuilderTriggerServer:
     enabled: true
   

   agentBuilderToolServer and agentBuilderTriggerServer are required for Fleet.

2. (Optional) Configure for Istio Gateway

   If you are using an Istio Gateway, you must use LangSmith version 0.13.38 or later. Add the following to your langsmith_config.yaml before upgrading:

   backend:
     agentBootstrap:
       extraEnv:
         - name: CLIO_INCLUDE_PATH_SUFFIX
           value: "false"
   
3. Apply the changes

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

   Verify that the agentBootstrap Job completed successfully. Unlike Deployments, a failed Job produces no running pods and fails silently:

   kubectl get jobs -n <namespace>
   

   The agentBootstrap Job should show 1/1 in the COMPLETIONS column. If it shows 0/1, inspect the Job logs (replace <release-name> with your Helm release name, typically langsmith):

   kubectl logs -n <namespace> -l job-name=<release-name>-agent-bootstrap
   

   Then verify the Fleet, Insights, and Polly pods are running:

   kubectl get pods -n <namespace>
   

(Optional) Enable OAuth tools and triggers for Fleet

To enable OAuth-based tools such as Gmail, Slack, or Linear in Fleet, configure the oauthProviderOrgId and add provider IDs for each integration you want to use. You can enable any combination of providers.

Available providers

Provider	Tools enabled	Trigger enabled
googleOAuthProvider setup guide	Gmail, Google Calendar, Google Sheets, BigQuery	Gmail
linearOAuthProvider setup guide	Linear	-
linkedinOAuthProvider setup guide	LinkedIn	-
microsoftOAuthProvider setup guide	Outlook, Calendar, Teams, SharePoint, Word, Excel, PowerPoint	Outlook
slackOAuthProvider setup guide	Slack	Slack

General configuration

Add the following to your langsmith_config.yaml. Include only the providers you need.

config:
  agentBuilder:
    # Organization ID where OAuth providers are configured
    oauthProviderOrgId: "<your-org-id>"
    oauth:
      # Add provider IDs for integrations you want to enable.
      # Slack requires additional configuration.
      slackOAuthProvider: "<provider-id>"
      slackSigningSecret: "<signing-secret>"
      slackBotId: "<bot-id>"
      googleOAuthProvider: "<provider-id>"
      linkedinOAuthProvider: "<provider-id>"
      linearOAuthProvider: "<provider-id>"
      microsoftOAuthProvider: "<provider-id>"

The provider ID must be unique and cannot end with -agent-builder or -oauth-provider.

Provider setup guides

Google OAuth provider

To enable Google OAuth for Fleet, create an OAuth client in GCP and configure it with the required URLs and credentials.

1. Create OAuth client in GCP

   Create a new OAuth client app (Web application) in Google Cloud Console.

2. Add URLs to GCP

   Add the following URLs to your OAuth client, replacing <hostname> with your LangSmith hostname and <provider-id> with the provider ID you’ll use (for example, google):

   Authorized JavaScript origins:

   • https://<hostname>

   Authorized redirect URIs:

   • https://<hostname>/api-host/v2/auth/callback/<provider-id>
   • https://<hostname>/host-oauth-callback/<provider-id>
3. Copy credentials

   Copy the Client ID and Client Secret from the GCP OAuth app.

4. Configure OAuth provider in LangSmith

   In LangSmith, go to Settings > OAuth Providers and add a new provider:

   • Client ID: from GCP
   • Client Secret: from GCP
   • Authorization URL: https://accounts.google.com/o/oauth2/auth
   • Token URL: https://oauth2.googleapis.com/token
   • Provider ID: Unique string, for example: google
5. Apply the changes

   Add the LangSmith OAuth provider ID to your langsmith_config.yaml and deploy:

   config:
     agentBuilder:
       oauthProviderOrgId: "<your-org-id>"
       oauth:
         googleOAuthProvider: "<provider-id>"
   

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

Microsoft OAuth provider

To enable Microsoft OAuth for Fleet, create an Azure app registration, add the required Microsoft Graph delegated permissions, and configure a Microsoft OAuth provider in LangSmith.

1. Create an Azure app registration

   In the Microsoft Entra admin center, go to Applications > App registrations and create a new registration.

2. Choose supported account types

   Select the account type that matches your deployment. If you need users from multiple Microsoft Entra tenants to authenticate, choose a multi-tenant option. If your deployment is limited to one tenant, you can use a single-tenant app registration.

3. Add the redirect URI

   Add the following web redirect URI, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

   https://<hostname>/host-oauth-callback/<provider-id>
   
4. Create a client secret

   In Certificates & secrets, create a new client secret. Copy the Application (client) ID and the generated client secret value.

5. Add Microsoft Graph delegated permissions

   In API permissions, add the following Microsoft Graph delegated permissions:

   • Mail.ReadWrite
   • Mail.Send
   • Calendars.ReadWrite
   • Team.ReadBasic.All
   • Channel.ReadBasic.All
   • Channel.Create
   • ChannelMessage.Send
   • ChannelMessage.Read.All
   • Chat.Create
   • Chat.ReadWrite
   • User.ReadBasic.All
   • Files.ReadWrite.All
   • Sites.ReadWrite.All

   LangSmith automatically requests offline_access for Microsoft providers so users can receive refresh tokens.

6. Grant tenant consent

   Grant admin consent for the tenant if your Microsoft 365 policies require it for these delegated permissions.

7. Configure OAuth provider in LangSmith

   In LangSmith, go to Settings > OAuth Providers and add a new provider:

   • Name: For example, Microsoft
   • Provider ID: Unique string, for example: microsoft-oauth-provider
   • Client ID: Application (client) ID from Azure
   • Client Secret: Client secret value from Azure
   • Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
   • Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
   • Provider Type: microsoft
   • Token endpoint auth method: client_secret_post

   If you created a single-tenant app registration, replace common in the authorization and token URLs with your tenant ID.

8. Apply the changes

   Add the following to your langsmith_config.yaml and deploy:

   config:
     agentBuilder:
       oauthProviderOrgId: "<your-org-id>"
       oauth:
         microsoftOAuthProvider: "<provider-id>"
   

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

Linear OAuth provider

To enable Linear OAuth for Fleet, create a Linear OAuth app and configure it with the required credentials.

1. Create a Linear OAuth app

   Go to Linear Settings > API > Applications and create a new OAuth application.

2. Add callback URL

   Set the callback URL, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

   https://<hostname>/host-oauth-callback/<provider-id>
   
3. Copy credentials

   After creating the app, copy the Client ID and Client Secret.

4. Configure OAuth provider in LangSmith

   In LangSmith, go to Settings > OAuth Providers and add a new provider:

   • Client ID: from Linear app
   • Client Secret: from Linear app
   • Authorization URL: https://linear.app/oauth/authorize
   • Token URL: https://api.linear.app/oauth/token
   • Provider ID: Unique string, for example: linear
5. Apply the changes

   Add the following to your langsmith_config.yaml and deploy:

   config:
     agentBuilder:
       oauthProviderOrgId: "<your-org-id>"
       oauth:
         linearOAuthProvider: "<provider-id>"
   

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

LinkedIn OAuth provider

To enable LinkedIn OAuth for Fleet, create a LinkedIn OAuth app and configure it with the required credentials.

1. Create a LinkedIn OAuth app

   Go to linkedin.com/developers/apps and create a new app.

2. Add redirect URI

   In your app settings, go to the Auth tab. Add the following redirect URI, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID:

   https://<hostname>/host-oauth-callback/<provider-id>
   
3. Copy credentials

   Copy the Client ID and Client Secret from the Auth tab.

4. Configure OAuth provider in LangSmith

   In LangSmith, go to Settings > OAuth Providers and add a new provider:

   • Client ID: from LinkedIn app
   • Client Secret: from LinkedIn app
   • Authorization URL: https://www.linkedin.com/oauth/v2/authorization
   • Token URL: https://www.linkedin.com/oauth/v2/accessToken
   • Provider ID: Unique string, for example: linkedin
5. Apply the changes

   Add the following to your langsmith_config.yaml and deploy:

   config:
     agentBuilder:
       oauthProviderOrgId: "<your-org-id>"
       oauth:
         linkedinOAuthProvider: "<provider-id>"
   

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

Slack OAuth provider

To enable Slack OAuth for Fleet, create a Slack app and configure it with the required scopes, credentials, and event subscriptions.

1. Create a Slack app

   Go to api.slack.com/apps and click Create New App.

2. Add scopes

   In OAuth & Permissions, add the following scopes:

   • channels:history
   • channels:read
   • chat:write
   • groups:history
   • groups:read
   • im:history
   • im:read
   • im:write
   • mpim:history
   • team:read
   • users:read
   • users:read.email
3. Copy credentials from Slack

   Copy the Client ID, Client Secret, and Signing Secret from the Slack app settings.

4. Configure OAuth provider in LangSmith

   In LangSmith, go to Settings > OAuth Providers and add a new provider:

   • Client ID: from Slack app
   • Client Secret: from Slack app
   • Authorization URL: https://slack.com/oauth/v2/authorize
   • Token URL: https://slack.com/api/oauth.v2.access
   • Provider ID: Unique string, for example: slack
5. Add redirect URI to Slack

   Add the following redirect URI to your Slack app under OAuth & Permissions > Redirect URLs, replacing <hostname> with your LangSmith hostname and <provider-id> with your provider ID (for example, slack):

   https://<hostname>/host-oauth-callback/<provider-id>
   
6. Get the bot ID

   1. Get the bot token from OAuth & Permissions in your Slack app.
   2. Run the following command:

   curl -X POST https://slack.com/api/auth.test \
     -H "Authorization: Bearer <bot-token>"
   

   3. Copy the bot_id from the response.
7. Apply the changes

   Add the following to your langsmith_config.yaml and deploy:

   config:
     agentBuilder:
       oauthProviderOrgId: "<your-org-id>"
       oauth:
         slackOAuthProvider: "<provider-id>"
         slackSigningSecret: "<signing-secret>"
         slackBotId: "<bot-id>"
   

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   
8. Enable event subscriptions

   1. After deployment, go to Event Subscriptions in your Slack app and enable events.

   2. Set the Request URL to:

      https://<hostname>/v1/triggers/webhooks/d809e66e-0000-4000-8000-000000000002
      

      The UUID is a fixed LangSmith identifier — do not replace it.

   3. Add the following bot events:

      • message.channels
      • message.groups
      • message.im
      • message.mpim
9. Set up triggers and tools

   1. Add the Slack bot to the channel you want it to read from.
   2. When configuring the Slack tool or trigger in Fleet, provide the channel ID and channel name.

(Optional) Enable GitHub App for Fleet

Fleet integrates with GitHub through a dedicated GitHub App (not an OAuth app). The GitHub App provides repository access for Fleet’s GitHub tools and supports the user authorization flow required for private repository access.

Setup involves creating a GitHub App, gathering its credentials, storing them as Kubernetes secrets, and referencing them from your langsmith_config.yaml.

1. Create a GitHub App

   Go to GitHub Settings > Developer settings > GitHub Apps and click New GitHub App.

   You can create the app under a personal account or an organization. If multiple people will manage the integration, an organization-owned app is recommended.

2. Fill in basic details

   • GitHub App name: Any unique name, for example acme-langsmith-fleet. Make a note of the slug GitHub generates (the lowercased, hyphenated form of the name), as this is the value you’ll use for FLEET_GITHUB_APP_SLUG.
   • Homepage URL: Your LangSmith hostname, for example https://langsmith.acme.com.
   • Deselect Active under Webhook for now. You’ll enable it in a later step after generating a webhook secret.
3. Set callback URLs

   Under Identifying and authorizing users, add the following Callback URL, replacing <hostname> with your LangSmith hostname:

   https://<hostname>/v1/platform/fleet/providers/github-app/auth/callback
   

   Select Redirect on update.

   Under Post installation, add the following Setup URL:

   https://<hostname>/v1/platform/fleet/providers/github-app/callback
   

   Select Redirect on update.

4. Set webhook URL and generate a webhook secret

   Generate a random webhook secret:

   python3 -c "import secrets; print(secrets.token_urlsafe(48))"
   

   Under Webhook:

   • Select Active.

   • Set the Webhook URL to:

     https://<hostname>/v1/platform/fleet/providers/github-app/webhooks
     

   • Paste the generated value into Webhook secret. Save it, as you’ll need the same value when creating the Kubernetes secret in a later step.

5. Set repository permissions

   Under Permissions > Repository permissions, grant the following:

   • Contents: Read and write
   • Issues: Read and write
   • Pull requests: Read and write
   • Metadata: Read-only (automatically selected)

   Under Permissions > Account permissions, grant Email addresses: Read-only.

   These are the minimum permissions required for Fleet’s built-in GitHub tools (issue management, pull request creation, repository content access). Adjust if you need additional tool capabilities.

6. Choose install visibility

   Under Where can this GitHub App be installed?, select the option that matches your distribution needs. For most self-hosted deployments, Only on this account is correct.

7. Create the app

   Click Create GitHub App. On the app settings page, note the following values:

   Value	Where to find it	Environment variable
   App ID	Numeric, at the top of the page	FLEET_GITHUB_APP_ID
   Public link	For example, https://github.com/apps/acme-langsmith-fleet	FLEET_GITHUB_APP_PUBLIC_LINK
   App slug	Last path segment of the public link	FLEET_GITHUB_APP_SLUG
   Client ID	Under About	FLEET_GITHUB_APP_CLIENT_ID

8. Generate a client secret

   Under Client secrets, click Generate a new client secret and copy the value. This is FLEET_GITHUB_APP_CLIENT_SECRET. GitHub only shows it once.

9. Generate a private key

   Scroll to Private keys and click Generate a private key. GitHub downloads a .pem file. Keep this file secure, as it grants full access to the GitHub App. The PEM contents are FLEET_GITHUB_APP_PRIVATE_KEY.

10. Generate a state JWT secret

    LangSmith signs short-lived OAuth state tokens with an HMAC key. Generate one:

    python3 -c "import secrets; print(secrets.token_urlsafe(48))"
    

    This is FLEET_GITHUB_APP_STATE_JWT_SECRET.

11. Create a Kubernetes secret

    Store the sensitive values in a Kubernetes secret:

    kubectl create secret generic fleet-github-app \
      --namespace <your-langsmith-namespace> \
      --from-literal=client_secret="<client-secret>" \
      --from-literal=webhook_secret="<webhook-secret>" \
      --from-literal=state_jwt_secret="<state-jwt-secret>" \
      --from-file=private_key=/path/to/fleet-app.private-key.pem
    

    For production deployments, manage this secret through your existing secrets workflow (for example, Sealed Secrets or External Secrets Operator). See Use an existing secret for more.

12. Add the configuration to your langsmith_config.yaml

    Add the following, replacing the placeholder values with the non-sensitive values gathered above:

    commonEnv:
      - name: FLEET_GITHUB_APP_ID
        value: "<app-id>"
      - name: FLEET_GITHUB_APP_SLUG
        value: "<app-slug>"
      - name: FLEET_GITHUB_APP_PUBLIC_LINK
        value: "https://github.com/apps/<app-slug>"
      - name: FLEET_GITHUB_APP_CLIENT_ID
        value: "<client-id>"
      - name: FLEET_GITHUB_APP_CLIENT_SECRET
        valueFrom:
          secretKeyRef:
            name: fleet-github-app
            key: client_secret
      - name: FLEET_GITHUB_APP_PRIVATE_KEY
        valueFrom:
          secretKeyRef:
            name: fleet-github-app
            key: private_key
      - name: FLEET_GITHUB_APP_WEBHOOK_SECRET
        valueFrom:
          secretKeyRef:
            name: fleet-github-app
            key: webhook_secret
      - name: FLEET_GITHUB_APP_STATE_JWT_SECRET
        valueFrom:
          secretKeyRef:
            name: fleet-github-app
            key: state_jwt_secret
    
    agentBuilderToolServer:
      deployment:
        extraEnv:
          - name: FLEET_GITHUB_APP_ENABLED
            value: "true"
    

    FLEET_GITHUB_APP_ENABLED must be set on the tool server so the GitHub tools are registered. The remaining FLEET_GITHUB_APP_* variables are consumed by the platform backend and live under commonEnv.

13. Deploy and install the app on repositories

    Run the following command to apply the changes:

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
    

    Once pods are healthy:

    1. In LangSmith, open a Fleet agent and go to the GitHub integration in the agent editor.
    2. Click Connect GitHub to install the app on the repositories Fleet should access.
    3. For private repositories, you must explicitly select each repository during installation.

    Each user must also authorize the GitHub App against their own GitHub account using the re-auth flow in LangSmith. This allows Fleet to resolve per-user tokens for tools that act on behalf of a user.

Disable features

To disable any combination of Fleet, Insights, and Polly, set the corresponding flags to false in your langsmith_config.yaml:

config:
  agentBuilder:
    enabled: false
  insights:
    enabled: false
  polly:
    enabled: false

Optional configuration

Configure additional data planes

In addition to the data plane created above, you can create more data planes in different Kubernetes clusters or in the same cluster under a different namespace. There are different ways to achieve this, so implement the solution that works best for your use case.

Prerequisites

1. Review cluster organization

   Read through the cluster organization guide in the hybrid deployment documentation to understand how to organize this for your use case.

2. Verify hybrid prerequisites

   Verify the prerequisites in the hybrid section for the new cluster. In step 5 of the prerequisites, configure egress to your self-hosted LangSmith instance instead of https://api.host.langchain.com and https://api.smith.langchain.com.

3. Enable the feature in Postgres

   Run the following against your LangSmith Postgres instance to enable this feature. Note the workspace ID for later steps.

   update organizations set config = config || '{"enable_lgp_listeners_page": true}' where id = '<org id here>';
   update tenants set config = config || '{"langgraph_remote_reconciler_enabled": true}' where id = '<workspace id here>';
   

Deploy to a different cluster

1. Follow the hybrid setup guide

   Follow steps 2 to 6 in the hybrid setup guide. Set config.langsmithWorkspaceId to the workspace ID from the previous step.

2. (Optional) Add more data planes to the same cluster

   To add more than one data plane to the same cluster, follow the instructions for configuring additional data planes in the same cluster.

Deploy to a different namespace in the same cluster

1. Update your config

   In your langsmith_config.yaml, make the following modifications:

   • Set operator.watchNamespaces to the current namespace your self-hosted LangSmith instance is running in. This prevents conflicts with the operator added by the new data plane.
   • Use the Gateway API or an Istio Gateway. Adjust your langsmith_config.yaml accordingly.
2. Apply the changes

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   
3. Follow the hybrid setup guide

   Follow steps 2 to 6 in the hybrid setup guide. Set config.langsmithWorkspaceId to the workspace ID from the previous step. Set config.watchNamespaces to a different namespace than the one used by the existing data plane.

4. (Optional) Configure log access

   Configure access for the control plane to read Agent Server deployment logs from the new namespace. See Read Agent Server logs from other namespaces.

Configure authentication for private registries

If your Agent Server deployments will use images from private container registries (for example, AWS ECR, Azure ACR, or GCP Artifact Registry), configure image pull secrets. This configuration applies to all deployments automatically, allowing them to authenticate with your private registry.

1. Create a Kubernetes image pull secret

   kubectl create secret docker-registry langsmith-registry-secret \
       --docker-server=myregistry.com \
       --docker-username=your-username \
       --docker-password=your-password \
       --docker-email=[e-mail] \
       -n langsmith
   

   Replace the values with your registry credentials:

   • myregistry.com: Your registry URL
   • your-username: Your registry username
   • your-password: Your registry password or access token
   • langsmith: The Kubernetes namespace where LangSmith is installed
2. Configure the deployment template in your langsmith_config.yaml

   To enable agent server deployments to use the private registry secret, add imagePullSecrets to the operator’s deployment template:

   operator:
     templates:
       deployment: |
         apiVersion: apps/v1
         kind: Deployment
         metadata:
           name: ${name}
           namespace: ${namespace}
         spec:
           replicas: ${replicas}
           revisionHistoryLimit: 10
           selector:
             matchLabels:
               app: ${name}
           template:
             metadata:
               labels:
                 app: ${name}
             spec:
               enableServiceLinks: false
               imagePullSecrets:
               - name: langsmith-registry-secret
               containers:
               - name: api-server
                 image: ${image}
                 ports:
                 - name: api-server
                   containerPort: 8000
                   protocol: TCP
                 livenessProbe:
                   httpGet:
                     path: /ok
                     port: 8000
                   periodSeconds: 15
                   timeoutSeconds: 5
                   failureThreshold: 6
                 readinessProbe:
                   httpGet:
                     path: /ok
                     port: 8000
                   periodSeconds: 15
                   timeoutSeconds: 5
                   failureThreshold: 6
   

3. Apply the changes

   helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug
   

   All user deployments created through the LangSmith UI will inherit these registry credentials.

For registry-specific authentication methods, refer to the Kubernetes documentation on pulling images from private registries.

Read Agent Server logs from other namespaces

Retrieving server logs is not supported for self-hosted deployments where the control plane (host-backend) and data plane (listener) are deployed in different Kubernetes clusters.

For deployments where the control plane and data plane are in the same cluster, ensure the control plane Kubernetes deployment (host-backend) has permission to get, list, and watch Kubernetes deployments, pods, replicasets, and logs from the namespace where the Agent Server deployment exists. There are different ways to achieve this. The following example uses Kubernetes RBAC, but use the approach that best fits your use case:

1. Create a Role with the required permissions

   Create a Role in the Agent Server namespace. Replace <data_plane_namespace>:

   kubectl apply -n <data_plane_namespace> -f - <<EOF
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: read-agent-server-logs-role
   rules:
   - apiGroups: [""]
     resources: ["pods"]
     verbs: ["get","list","watch"]
   - apiGroups: [""]
     resources: ["pods/log"]
     verbs: ["get","watch"]
   - apiGroups: ["apps"]
     resources: ["deployments"]
     verbs: ["get","list","watch"]
   - apiGroups: ["apps"]
     resources: ["replicasets"]
     verbs: ["get","list","watch"]
   EOF
   
2. Get the control plane ServiceAccount

   Replace <control_plane_namespace>:

   kubectl get serviceaccounts -n <control_plane_namespace> | grep host-backend
   
3. Bind the Role to the control plane ServiceAccount

   Replace <data_plane_namespace>, <control_plane_namespace>, and <control_plane_service_account>:

   kubectl apply -n <data_plane_namespace> -f - <<EOF
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: read-agent-server-logs-role-binding
   subjects:
   - kind: ServiceAccount
     name: <control_plane_service_account>
     namespace: <control_plane_namespace>
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: read-agent-server-logs-role
   EOF
   

In this example, the Role and RoleBinding are defined in the same Kubernetes namespace as the Agent Server deployment. You can assign any name to the Role and RoleBinding and customize them as needed.

Next steps

Once your infrastructure is set up, you’re ready to deploy agent applications. See the deployment guides for instructions on building and deploying your agent applications.

---

Edit this page on GitHub or file an issue.

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