> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.
# Self-Hosting Langy
> Requirements and architecture for running Langy on your own Kubernetes cluster, including the separate agent pod and the optional gVisor sandbox.
Langy runs as a separate Kubernetes Deployment, the `langyagent` pod, and ships **enabled**: a plain `helm install` deploys it, materialises the shared secret, wires the app and workers to it, and opens Langy to everyone in the install.
By default the pod runs on the node's normal container runtime, so it starts on any cluster. To isolate it from the host, pin it to a sandboxed RuntimeClass such as `gvisor`. See [Setup](https://langwatch.ai/docs/self-hosting/langy/setup.md).
The GitHub App and outbound network egress are both optional and off until you configure them.
The `langyagent` pod is a single Go "manager" process that spawns one [agent worker](https://langwatch.ai/docs/langy/how-langy-works.md) per conversation. Workers run on the node's normal runtime by default; set a sandboxed `runtimeClassName` to harden them. It never talks to your data stores directly; each worker reaches LangWatch only through the `langwatch` CLI, over the per-session credentials the control plane mints for that turn.
> [!NOTE]
>
> **Also check:** [Setup](https://langwatch.ai/docs/self-hosting/langy/setup.md), [Environment
> variables](https://langwatch.ai/docs/self-hosting/langy/environment-variables.md), [Networking and
> egress](https://langwatch.ai/docs/self-hosting/langy/networking-and-egress.md), [The sandbox](https://langwatch.ai/docs/langy/security/sandbox.md).
> [!NOTE]
>
> **Turning Langy off.** Set `langyagent.chartManaged: false`: the agent pod and every reference to it are removed on the next upgrade, and every other part of the install is left as it was. For opening Langy to a few projects before everyone, see [staged rollout](https://langwatch.ai/docs/self-hosting/langy/setup.md#staged-rollout). On LangWatch Cloud, availability is managed for you.
## At a glance
| | |
| - | - |
| Deployment | Separate `langyagent` Deployment + ConfigMap + Service + NetworkPolicy in the umbrella chart |
| Default state | On (`langyagent.chartManaged: true`); disable with `chartManaged: false` |
| Access | Everyone in the install (`enableForAllUsers: true`); staged rollout via the flag instead |
| Replicas | 1 (render-time guard blocks more until conversation-sticky routing exists) |
| Update strategy | `Recreate`, no HPA. Scale vertically. |
| Sandbox | None by default (`runtimeClassName: ""`, `acceptUnsandboxedRuntime: true`); set `runtimeClassName` and `acceptUnsandboxedRuntime: false` to require one |
| Sizing | \~5 to 15 concurrent sessions at 500m to 2 CPU / 1 to 4Gi |
| Shared secret | `LANGY_INTERNAL_SECRET`, materialised in the app Secret by the chart; add it to your own Secret when `autogen.enabled: false` |
| GitHub App | Optional, for bot-authored pull requests |
| Outbound egress | Off by default (`networkPolicy.allowExternalHttps: false`) |
## Hard requirements
* **A sandboxed runtime, for hardening.** The workload is LLM-driven arbitrary shell (workers spawn `git`, `gh`, and `npm`). The default runs it on the node's normal runtime so the install works on any cluster; for production, pin the pod to a sandboxed RuntimeClass and set `acceptUnsandboxedRuntime: false`. On a cluster without that RuntimeClass, the pod then waits with a `RuntimeClass not found` event. See [The sandbox](https://langwatch.ai/docs/langy/security/sandbox.md).
* GKE ships the RuntimeClass managed (GKE Sandbox; Autopilot schedules `gvisor` pods directly).
* On AKS, point `runtimeClassName` at your Kata VM isolation class; any sandboxed RuntimeClass works.
* EKS has no managed option: install gVisor on a node group ([Setup](https://langwatch.ai/docs/self-hosting/langy/setup.md#eks-install-gvisor-on-a-node-group)).
* **A separate pod and service.** The agent is its own Deployment, ConfigMap, ClusterIP Service, and NetworkPolicy (plus an optional PodDisruptionBudget and CiliumNetworkPolicy). It runs a single replica with `strategy: Recreate` and no HPA, sized for roughly 5 to 15 concurrent sessions at 500m to 2 CPU and 1 to 4Gi. Scale it vertically, not horizontally.
* **The shared internal secret.** The app and the agent authenticate to each other with a bearer token, `LANGY_INTERNAL_SECRET`. The chart materialises it in the app Secret when `autogen.enabled` is on; with your own Secret, add the key yourself. Under plain `helm` the install checks for it before starting. See [Setup](https://langwatch.ai/docs/self-hosting/langy/setup.md#bringing-your-own-secrets).
## Optional components
* **GitHub App** for bot-authored pull requests. Register a GitHub App and set the `GITHUB_LANGY_*` env vars. If the private key is unset, the GitHub feature is silently off and Langy returns findings without opening PRs. See [Register the Langy GitHub App](https://langwatch.ai/docs/self-hosting/langy/github-app.md).
* **Outbound HTTPS egress** for `git`, `gh`, and `npm`. `networkPolicy.allowExternalHttps` is `false` by default; the pod cannot reach GitHub until you enable egress. See [Networking and egress](https://langwatch.ai/docs/self-hosting/langy/networking-and-egress.md).
* **Operator mirror lane** to copy Langy's own turn traces into a LangWatch project you designate, so whoever runs the install can watch Langy work. Off until `langyagent.mirror.existingSecretName` names a Secret holding the mirror project's API key. See [Watching Langy work](https://langwatch.ai/docs/self-hosting/langy/setup.md#watching-langy-work).
## Architecture
```mermaid theme={null}
graph LR
Browser["Browser
(event-sourced UI)"] -->|"HTTPS"| App["LangWatch App
(control plane)"]
App -->|"Bearer LANGY_INTERNAL_SECRET
ClusterIP only"| Agent["langyagent pod
(Go manager)"]
Agent -->|"one per conversation"| Worker["agent worker"]
Worker -->|"langwatch CLI
(per-session key)"| App
Worker -->|"LLM traffic
(virtual key)"| Gateway["LangWatch AI Gateway"]
Gateway -->|"completions"| Providers["LLM Providers
(your accounts / BYOK)"]
Worker -->|"git / gh
(if egress on)"| GitHub["github.com
api.github.com
codeload.github.com"]
App -->|"install tokens"| GitHubAPI["api.github.com"]
```
The control plane reaches the agent over cluster DNS at `http://-langyagent:80` (`LANGY_AGENT_URL`), authenticated with `LANGY_INTERNAL_SECRET`. The Service is ClusterIP only; a render-time guard blocks any other type, so the agent is never exposed outside the cluster.
Each worker's only path to LangWatch data is the `langwatch` CLI, and its only path to the internet is the [L7 egress adapter](https://langwatch.ai/docs/self-hosting/langy/networking-and-egress.md). LLM traffic goes through the [LangWatch AI Gateway](https://langwatch.ai/docs/ai-gateway/self-hosting/helm.md), never direct to providers, so every Langy LLM call is traced, budgeted, and policed like any other.
## Where to go next
> [card] [Setup](https://langwatch.ai/docs/self-hosting/langy/setup.md)
>
> Deployed by default; the sandboxed runtime per cloud, egress, mirror, and staged rollout.
> [card] [Register the GitHub App](https://langwatch.ai/docs/self-hosting/langy/github-app.md)
>
> Register the app, set the `GITHUB_LANGY_*` env vars, and install it on the repos Langy may
> touch.
> [card] [Environment variables](https://langwatch.ai/docs/self-hosting/langy/environment-variables.md)
>
> The full `LANGY_*` and `GITHUB_LANGY_*` reference with defaults.
> [card] [Networking and egress](https://langwatch.ai/docs/self-hosting/langy/networking-and-egress.md)
>
> The NetworkPolicy, the FQDN floor, and the cooperative-vs-mandatory egress limit.
> [card] [The sandbox](https://langwatch.ai/docs/langy/security/sandbox.md)
>
> What the gVisor sandbox can and cannot reach, and where the boundaries sit.
> [card] [Platform self-hosting](https://langwatch.ai/docs/self-hosting/overview.md)
>
> Deploy the rest of the LangWatch stack that Langy runs alongside.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.