> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-ramonn-1789138246-3410f5f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangSmith Engine on Self-hosted

> Install LangSmith Engine on a self-hosted LangSmith instance, and understand what it depends on outside your environment and how it handles your data.

<Info>
  Self-hosted Engine requires LangSmith Helm chart `0.16.0` or later and a license that includes the Engine entitlement. It is not available on earlier chart versions. [Contact our sales team](https://www.langchain.com/contact-sales) to have the entitlement added to your order.
</Info>

LangSmith Engine is an agent within LangSmith that monitors your production traces, clusters them into issues, diagnoses each issue against your source code, proposes a fix as a PR, and identifies ground truth evals to add to your datasets. For a product overview, see [Engine](/langsmith/engine-overview).

In self-hosted LangSmith, Engine's orchestration, including its detect, fix, and verify loop, runs inside your VPC as part of LangSmith. Model work cannot run entirely in your VPC: Engine sends the content it needs to LangSmith Intelligence (LSI), a LangChain-managed zero data retention (ZDR) service.

This page covers both halves: what Engine depends on outside your environment, and how to [install Engine](#install-engine) on your instance. To connect Engine to your source code, create and configure your own GitHub App as described in [Connect Engine to GitHub](/langsmith/engine-github).

Engine works with three kinds of data:

* **Code** (optional)**:** Your agent's source, which Engine reads to diagnose issues and propose fixes.
* **Traces:** Runtime data from your agents, which can include user messages, tool outputs, and PII.
* **Model:** The LLM calls Engine makes to run diagnosis, generate fixes, and write evaluators.

## Availability by cloud and region

Engine is available where LSI is available:

| Cloud | Region | Status    |
| ----- | ------ | --------- |
| AWS   | US     | Available |
| GCP   | US     | Available |

For availability in other regions, [contact our sales team](https://www.langchain.com/contact-sales).

## How it works

LSI is the LangChain-managed service that powers Engine.

The flow:

* Your self-hosted Engine sends an HTTPS request to the LSI gateway for its cloud, listed in the per-cloud sections on this page.
* Engine authenticates with a short-lived license JWT obtained during LangSmith license verification. You do not provide separate model-provider credentials.
* LSI validates the JWT and routes the request to the model provider over private networking inside LangChain's environment.
* LSI returns the response to your self-hosted Engine.

Each request carries the trace content, code, and intermediate outputs Engine needs to do its work. LSI and the model provider process that content to serve the request.

Your cluster must allow outbound HTTPS to that gateway. The connection can use public egress or private connectivity. On AWS, follow [Connect with AWS PrivateLink](#connect-with-aws-privatelink) to keep Engine traffic on private networking.

If the connection to LSI is unavailable, Engine stops and returns an error rather than degrading to lower-quality output. There is no in-cluster model and no secondary provider to fall back on. The rest of your LangSmith deployment is unaffected, and Engine tries again on its next scheduled scan.

## What LangSmith Intelligence retains

LSI does not persist the content of prompts or model responses. It retains the following metadata for usage attribution and billing:

* Account, workspace, and project identifiers used to attribute usage.
* Model and token-usage metadata used for billing.

For model-provider retention and training commitments, see [Engine security](/langsmith/engine-security).

## Connect by cloud

### AWS (available in US)

The gateway host is [`beacon.aws.langchain.com`](#allow-egress-to-langsmith-intelligence). LSI routes requests to AWS Bedrock in LangChain's AWS environment.

#### Connect with AWS PrivateLink

Before configuring PrivateLink, complete [Install Engine](#install-engine), including its Helm and egress configuration.

[AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/) routes Engine traffic from your VPC to LSI without exposing that traffic to the public internet. The LSI endpoint service is hosted in `us-east-2`, and AWS supports access from VPCs in other regions.

Before you begin, collect your AWS account ID, VPC ID, private subnet IDs, and a security group for the interface endpoint. Configure that endpoint security group to allow inbound TCP traffic on port 443 only from the security group attached to the nodes or workloads that run Engine, or from the smallest private CIDR that contains them. Do not allow `0.0.0.0/0`.

To connect your VPC to LSI:

<Steps>
  <Step title="Request access">
    Contact your account representative or [sales@langchain.dev](mailto:sales@langchain.dev) with your AWS account ID. LangChain adds your account to the endpoint service's allowed principals list.
  </Step>

  <Step title="Create the interface VPC endpoint">
    Configure the AWS provider for the region that contains your VPC. Keep `service_region` set to `us-east-2`, including when your VPC is in another region. Select one private subnet per availability zone.

    <Note>
      The `service_region` argument requires HashiCorp AWS provider `5.82.0` or later.
    </Note>

    ```hcl theme={null}
    resource "aws_vpc_endpoint" "langsmith_intelligence" {
      vpc_id              = var.vpc_id
      service_name        = "com.amazonaws.vpce.us-east-2.vpce-svc-054f37092752bff6b"
      service_region      = "us-east-2"
      vpc_endpoint_type   = "Interface"
      subnet_ids          = var.private_subnet_ids
      security_group_ids  = [var.security_group_id]
      private_dns_enabled = false
    }
    ```
  </Step>

  <Step title="Wait for LangChain to accept the connection">
    The endpoint status changes from `pendingAcceptance` to `available` after LangChain accepts the connection. Allow a few minutes for the change to propagate before testing connectivity.
  </Step>

  <Step title="Route the LSI hostname to the endpoint">
    Enable DNS resolution and DNS hostnames for your VPC. Then, create a Route 53 private hosted zone and alias record so `beacon.aws.langchain.com` resolves to the VPC endpoint inside your VPC. Keep this hostname unchanged so TLS certificate validation succeeds. The private hosted zone also prevents fallback to public DNS when the endpoint is unavailable.

    ```hcl theme={null}
    resource "aws_route53_zone" "langsmith_intelligence" {
      name = "beacon.aws.langchain.com"

      vpc {
        vpc_id = var.vpc_id
      }
    }

    resource "aws_route53_record" "langsmith_intelligence" {
      zone_id = aws_route53_zone.langsmith_intelligence.zone_id
      name    = "beacon.aws.langchain.com"
      type    = "A"

      alias {
        name                   = aws_vpc_endpoint.langsmith_intelligence.dns_entry[0].dns_name
        zone_id                = aws_vpc_endpoint.langsmith_intelligence.dns_entry[0].hosted_zone_id
        evaluate_target_health = true
      }
    }
    ```

    If workloads use a corporate DNS resolver instead of the Amazon-provided resolver, configure conditional forwarding to Route 53 Resolver or create an equivalent private DNS override for `beacon.aws.langchain.com` that points to the endpoint DNS name.
  </Step>

  <Step title="Verify private connectivity">
    From a node or container that runs Engine, resolve the gateway hostname:

    ```bash theme={null}
    getent ahostsv4 beacon.aws.langchain.com
    ```

    Confirm that the result contains the private IP addresses assigned to the endpoint network interfaces. Then start an analysis and confirm that it completes successfully. If the analysis does not complete, review the Engine installation and egress configuration.
  </Step>
</Steps>

<Frame caption="AWS: LangSmith and Engine run in your VPC; LSI and Bedrock run in LangChain's AWS environment.">
  <img src="https://mintcdn.com/langchain-5e9cc07a-preview-ramonn-1789138246-3410f5f/1wTETgl21fTEIjvI/langsmith/images/engine-self-hosted-aws.png?fit=max&auto=format&n=1wTETgl21fTEIjvI&q=85&s=a2a62852f1c2a1189f9348ceaedfc45b" alt="Architecture diagram of self-hosted LangSmith in your VPC connected by AWS PrivateLink to LangSmith Intelligence and Bedrock in LangChain's AWS environment." width="2240" height="1540" data-path="langsmith/images/engine-self-hosted-aws.png" />
</Frame>

### GCP (available in US)

The gateway host is [`beacon.langchain.com`](#allow-egress-to-langsmith-intelligence). LSI routes requests to Vertex in LangChain's GCP environment.

<Note>
  This is the same host self-hosted LangSmith uses for license verification and billing telemetry, so a GCP deployment adds a path rather than a new egress destination. See [Configure egress](/langsmith/self-host-egress).
</Note>

<Frame caption="GCP: LangSmith and Engine run in your project; LSI and Vertex run in LangChain's GCP environment.">
  <img src="https://mintcdn.com/langchain-5e9cc07a-preview-ramonn-1789138246-3410f5f/1wTETgl21fTEIjvI/langsmith/images/engine-self-hosted-gcp.png?fit=max&auto=format&n=1wTETgl21fTEIjvI&q=85&s=6f9d17782bdc7a24abd2d9fde635f8ad" alt="Architecture diagram of self-hosted LangSmith in your GCP project connected to LangSmith Intelligence and Vertex in LangChain's GCP environment." width="2240" height="1540" data-path="langsmith/images/engine-self-hosted-gcp.png" />
</Frame>

## Model selection and quality

Engine uses different models, each tuned for its role, to cluster issues, diagnose root causes against your code, generate fixes, and write evaluators that verify them. LangChain tunes these models for quality and token efficiency, and updates them as better models become available.

Engine uses managed inference, not a bring-your-own-key setup. This keeps Engine behavior consistent and improves it as LangChain updates the models. With a bring-your-own-key setup, model selection, tuning, and token efficiency can vary between requests.

## Where Engine processes data

In a self-hosted deployment, Engine separates data handling between your environment and LangChain's:

* **Your environment:** Engine orchestration and LangSmith-stored traces remain in your self-hosted environment.
* **LangChain's environment:** LSI and the model provider process content that Engine sends. LSI retains the billing metadata described above.

Engine's deployment-independent data handling, including zero data retention with every model provider and no use of customer data to train or fine-tune models, is described in [Engine security](/langsmith/engine-security).

## Install Engine

Engine is disabled by default. It requires [Sandboxes](/langsmith/deploy-self-hosted-full-platform#enable-sandboxes), a connection to [LangSmith Intelligence](#allow-egress-to-langsmith-intelligence), an externally reachable [`config.hostname`](#verify-your-hostname-is-externally-reachable), and an [Engine encryption key](#generate-the-engine-encryption-key). Complete the prerequisites before enabling Engine.

Engine and [Insights](/langsmith/deploy-self-hosted-full-platform#enable-fleet-insights-and-chat) run from the same image and share one deployment. Insights is not required for Engine. If your installation already runs Insights, enabling Engine adds configuration rather than new pods.

### Components

Enabling Engine provisions or reuses:

* `standalone-insights-api-server`: serves both the `engine` and `insights` graphs.
* `standalone-insights-queue`: background run processing for Engine and Insights.
* A dedicated PostgreSQL and Redis instance for the shared deployment, each replaceable with an external instance.
* The sandbox components described under [Enable Sandboxes](/langsmith/deploy-self-hosted-full-platform#enable-sandboxes).

Engine also adds configuration to `platform-backend` and `ingest-queue`, which dispatch and schedule its runs.

### Prerequisites

<Steps>
  <Step title="Enable Sandboxes">
    Complete [Enable Sandboxes](/langsmith/deploy-self-hosted-full-platform#enable-sandboxes) first, including the KVM-capable node pool and JuiceFS storage.

    Engine's sandboxes are associated with one workspace. An install with Engine must have a [shared organization](/langsmith/administration-overview#organizations). If the shared organization has exactly one workspace, LangSmith uses that workspace. If the shared organization has more than one workspace, LangSmith does not choose one automatically. You must set `engine.sandboxTenantId` to the workspace ID.

    <Warning>
      Use a workspace reserved for Engine:

      * Engine's sandboxes are not billed on the Sandboxes product because Engine meters its own usage in LCUs.
      * Engine's sandboxes use the same concurrent sandbox, CPU, and memory quotas as other sandboxes in the workspace. If the workspace is near its limits, Engine runs can fail or leave less capacity for interactive sandboxes.
      * Engine's sandboxes are listed in that workspace and can be stopped by anyone with access to it.
      * Each sandbox runs agent-generated code.
      * Repository credentials remain in the sandbox auth proxy and are not available to code running inside the sandbox.
    </Warning>
  </Step>

  <Step title="Confirm the license entitlement">
    Engine is licensed separately, in the same way as Sandboxes. Your license must carry the Engine entitlement. LangSmith validates your license key against `https://beacon.langchain.com` at startup and periodically thereafter, so the entitlement takes effect without you changing any configuration once it is added to your order.
  </Step>

  <Step title="Allow egress to LangSmith Intelligence" id="allow-egress-to-langsmith-intelligence">
    Allow outbound HTTPS from the cluster to the LangSmith Intelligence gateway URL for your cloud. Use this URL as the value of `engine.intelligenceBaseUrl`.

    | Cloud | `engine.intelligenceBaseUrl`                    |
    | ----- | ----------------------------------------------- |
    | AWS   | `https://beacon.aws.langchain.com/intelligence` |
    | GCP   | `https://beacon.langchain.com/intelligence`     |

    On GCP, this uses the same host LangSmith already uses for license verification and billing telemetry, so Engine adds a path rather than a new egress destination.

    <Note>
      Engine is available for self-hosted deployments in **AWS US** and **GCP US**. Check [Availability by cloud and region](#availability-by-cloud-and-region) and confirm coverage with [our sales team](https://www.langchain.com/contact-sales) before planning a rollout.
    </Note>

    Add the gateway as a specific allowlist entry rather than opening general egress. To keep AWS traffic on private networking, [connect to LangSmith Intelligence with AWS PrivateLink](#connect-with-aws-privatelink). Requests use a short-lived license JWT obtained during LangSmith license verification. Engine's traffic is separate from the billing and operational telemetry described in [Configure egress](/langsmith/self-host-egress), even where it shares a host.

    <Note>
      Offline (air-gapped) installs cannot run Engine. There is no in-cluster model for it to fall back on.
    </Note>
  </Step>

  <Step title="Verify your hostname is externally reachable" id="verify-your-hostname-is-externally-reachable">
    Engine's sandboxes call your LangSmith install using the `langsmith` CLI, so `config.hostname` must be reachable from the sandbox network. Helm validation rejects `localhost` and in-cluster `*.svc` addresses.

    Serve that hostname through your ingress with TLS, as described in [Set up an ingress](/langsmith/self-host-ingress). Engine does not require you to expose anything beyond the address your own users already reach. Sandbox egress is allowlisted to your LangSmith hostname, `github.com`, `api.github.com`, and the Python package registries. Per-run credentials are injected by a proxy outside the sandbox rather than being readable inside it.
  </Step>

  <Step title="Generate the Engine encryption key" id="generate-the-engine-encryption-key">
    Engine uses its own Fernet key to encrypt the run payloads LangSmith passes to it, which carry short-lived credentials. Generate one:

    ```bash theme={null}
    python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
    ```

    Store it in your predefined Kubernetes Secret as `engine_encryption_key` rather than in your config file. See [Use an existing secret](/langsmith/self-host-using-an-existing-secret#parameters).

    To rotate the key later, copy the current value to `engine_encryption_key_previous` and set the new key as `engine_encryption_key`. The previous key is accepted for decryption only, so runs encrypted just before the swap still complete.
  </Step>
</Steps>

### Enable with Helm

Add the following to your [`langsmith_config.yaml`](/langsmith/kubernetes#configure-your-helm-charts), alongside the complete Sandboxes values from [Enable Sandboxes](/langsmith/deploy-self-hosted-full-platform#enable-sandboxes). These examples show only the Engine-specific values and the `sandboxes.enabled` flag.

<Tabs>
  <Tab title="Using Kubernetes secrets (recommended)">
    Reference your existing Secret by name. The chart reads `engine_encryption_key` from it automatically.

    ```yaml theme={null}
    config:
      existingSecretName: "<your-secret-name>"
      # Must be reachable from the sandbox network.
      hostname: "https://langsmith.example.com"

    engine:
      enabled: true
      intelligenceBaseUrl: "https://beacon.aws.langchain.com/intelligence"

    sandboxes:
      enabled: true
    ```
  </Tab>

  <Tab title="Using inline values">
    Set the encryption key directly in your config file.

    <Warning>
      This puts a live credential in your config file. Do not commit it to version control; prefer the Kubernetes Secret.
    </Warning>

    ```yaml theme={null}
    config:
      hostname: "https://langsmith.example.com"

    engine:
      enabled: true
      intelligenceBaseUrl: "https://beacon.aws.langchain.com/intelligence"
      encryptionKey: "<engine-encryption-key>"

    sandboxes:
      enabled: true
    ```
  </Tab>
</Tabs>

<Note>
  If your install has a shared organization with more than one workspace, set the workspace that owns Engine's sandboxes:
</Note>

```yaml theme={null}
engine:
  sandboxTenantId: "<workspace-id>"
```

<Warning>
  Upgrades from older Insights image pins require one extra check: if your values pin `images.engineInsightsAgentImage.repository` to the retired `langsmith-clio` image, remove or update that pin. Engine and Insights now run on `langsmith-insights-engine`, and the chart rejects `langsmith-clio`. For more information, see [Mirror images for your LangSmith installation](/langsmith/self-host-mirroring-images#additional-images-for-engine).
</Warning>

Validate the updated chart before applying it:

```bash theme={null}
helm template langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace>
```

The chart validates the Engine configuration at render time and fails with a message naming the missing value, so this command catches a misconfiguration before it reaches your cluster.

Apply the updated chart:

```bash theme={null}
helm upgrade -i langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace> \
  --wait
```

### Verify the installation

Confirm the shared Engine and Insights deployment is running:

```bash theme={null}
kubectl get pods -n <namespace> | grep standalone-insights
```

Both the API server and queue pods should be `Running`. Then, confirm `platform-backend` is healthy, since it dispatches Engine runs:

```bash theme={null}
kubectl rollout status deployment/langsmith-platform-backend -n <namespace>
```

If Engine does not appear in the LangSmith UI after this, the most common causes are a license without the Engine entitlement and the organization-level toggle described in [Turn on Engine in LangSmith](#turn-on-engine-in-langsmith).

After [enabling and configuring Engine](#turn-on-engine-in-langsmith) in the LangSmith UI, start an Engine analysis and confirm that results appear for the tracing project. This verifies the complete path through Engine, Sandboxes, and LangSmith Intelligence. Running pods alone does not verify that path.

If the analysis does not complete, check that Engine pods are running, the sandbox workspace has quota available, and the cluster can reach the LangSmith Intelligence gateway URL configured in `engine.intelligenceBaseUrl`.

### Turn on Engine in LangSmith

Enabling Engine in Helm makes the feature available; it does not start any scans. After enabling the chart values, finish setup in LangSmith:

1. An [Organization Admin](/langsmith/rbac#organization-admin) turns Engine on for the organization under **Settings > Engine enablement**. For more information, see [Find and fix issues](/langsmith/engine#enable-engine-for-your-organization).
2. Any user sets Engine up for a tracing project from the project's **Engine** tab. For more information, see [Set up Engine for a tracing project](/langsmith/engine#set-up-engine-for-a-tracing-project).

Connecting a GitHub repository is optional and improves Engine's diagnosis and fixes. Without one, Engine cannot read your source code or open pull requests. To create the GitHub App and configure `host-backend`, see [Connect Engine to GitHub](/langsmith/engine-github#self-hosted).

### Disable Engine

Set `engine.enabled` to `false` and re-apply:

```yaml theme={null}
engine:
  enabled: false
```

Engine stops dispatching runs. Insights shares the same deployment, so the `standalone-insights` pods keep running when `insights.enabled` is `true`.

## See also

* [Engine](/langsmith/engine-overview)
* [Configure Engine](/langsmith/engine)
* [Connect Engine to GitHub](/langsmith/engine-github)
* [Engine security](/langsmith/engine-security)
* [Engine webhooks](/langsmith/engine-webhooks)
* [Enable additional LangSmith features](/langsmith/deploy-self-hosted-full-platform)

***

<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/engine-self-hosted.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>