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

# How Langy works

> Each Langy conversation is one agent worker in a gVisor sandbox: it reads LangWatch through the langwatch CLI, calls models through the LangWatch AI Gateway, and ships code only as pull requests.

Langy runs as a separate service, `langyagent`, next to the LangWatch app. The app dispatches each chat turn to it; `langyagent` keeps one agent worker process per conversation and reaps it when the conversation goes idle.

The worker does the actual reading, testing, and code editing. Every tool call it makes streams back into the chat as a typed activity, and every turn is a traced run in your project.

> [!NOTE]
>
> **Also check:** [Security and the sandbox](https://langwatch.ai/docs/langy/security/sandbox.md), [Self-hosting
> overview](https://langwatch.ai/docs/self-hosting/langy/overview.md)

## The architecture

```mermaid theme={null}
graph LR
  browser["Browser<br/>(event-sourced chat UI)"]
  control["LangWatch control plane<br/>(turn processor, event log)"]
  manager["langyagent pod<br/>(Go manager)"]
  worker["Agent worker<br/>(one per conversation, gVisor-sandboxed)"]
  cli["langwatch CLI<br/>&rarr; LangWatch API"]
  gateway["LangWatch AI Gateway<br/>(model calls)"]
  github["GitHub App<br/>(bot-authored PRs)"]

  browser <--> control
  control <-->|"LANGY_INTERNAL_SECRET bearer<br/>ClusterIP only"| manager
  manager --> worker
  worker --> cli
  worker --> gateway
  worker --> github
  worker -.->|"each turn is a traced run"| control
```

| Piece | What it does |
| - | - |
| Browser | The chat panel. Event-sourced: a refresh resumes the conversation, an in-flight turn keeps streaming. |
| Control plane | The turn processor in the LangWatch app. Admits each turn, dispatches it to the agent, logs every tool call as a typed event. |
| `langyagent` | The agent service. Spawns one worker per conversation. Single replica; scale vertically. |
| Agent worker | The coding agent itself, inside the gVisor sandbox, holding that conversation's credentials, repo clone, and skills. Reaped after \~10 minutes idle, home wiped. |

The agent service is cluster-internal only, never exposed outside; auth and networking details are on the [self-hosting overview](https://langwatch.ai/docs/self-hosting/langy/overview.md).

The worker has exactly three ways out:

* **The `langwatch` CLI** for your LangWatch data: `trace search`, `analytics query`, `scenario create`, `experiment run`. No MCP server, no internal API.
* **The LangWatch AI Gateway** for every model call, never a provider directly, so each call is traced, rate-limited, and policy-checked on your own keys or Codex. See [Models](https://langwatch.ai/docs/langy/models.md) and [Codex](https://langwatch.ai/docs/langy/codex.md).
* **The GitHub App** for code changes, only as pull requests. See [Pull requests](https://langwatch.ai/docs/langy/pull-requests.md).

## The session loop

**1. You ask**

You send a turn in plain language. The control plane admits it and dispatches it to the manager,
which spawns (or reuses a warm) worker for that conversation with the turn's credentials bound
at spawn.

**2. Langy reads the traces and evals**

The worker runs `langwatch` CLI commands to pull the traces, analytics, and evals your question
points at. Each command streams back into the conversation as an activity card, so you see what
it searched.

**3. It writes a failing Scenario test or evaluation**

When the answer is a code change, Langy writes a Scenario multi-turn simulation or an evaluation
that captures the problem, so the fix has something to prove against.

**4. It drafts a fix and opens a pull request**

Langy clones the installed repo inside the worker, drafts the change, and opens a bot-authored
pull request. The clone lives only in the worker's home and is wiped when the worker is reaped.

**5. Your CI runs the tests it wrote**

The Scenario tests Langy wrote run in your CI on that PR. The PR card returns with the result,
so you see the diff and the check status together.

**6. A human reviews and merges**

You read the PR and merge it. Langy never merges its own PR.

> [!NOTE]
>
> Every turn Langy takes re-enters LangWatch as its own traced, costed run in your project. You
> debug Langy with the same traces and evals you use to debug your own agents.

For how the sandbox isolates each worker and exactly what it can and cannot reach on the network, see [Security and the sandbox](https://langwatch.ai/docs/langy/security/sandbox.md). For running this stack yourself, see the [self-hosting overview](https://langwatch.ai/docs/self-hosting/langy/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.