# Sync to LangGraph Platform

LangGraph Platform runs your Agent Server for you, which means there is no
container to inject into: the deployment's **secrets** are its environment, and
the control plane is the only way to set them. A binding owns one deployment's
secrets.

| At a glance | |
| --- | --- |
| **What seekrit writes** | A deployment's `secrets`, delivered to the agent container as environment variables |
| **Addressed by** | The deployment UUID |
| **Connection carries** | The region (or a self-hosted control-plane URL), and a workspace ID for org-scoped keys |
| **Token permission** | A LangSmith API key that can update the deployment |
| **Takes effect** | On the **new revision** the write creates — a rebuild and rollout |
| **Value visibility** | Readable through the control plane by anyone with a key for the workspace |

New to sync? Read [Third-party sync](/docs/guides/third-party-sync) first — the
decryption grant, name mapping, deletions, and failure handling are the same on
every destination.

> **Warning:** **A push redeploys the agent.** LangGraph Platform applies a secret change by
>   creating a new revision, and its control plane offers no way to stage a value
>   without shipping it. In-flight runs are interrupted.
> 
> seekrit keeps that to the minimum it can: it reads the deployment first and
>   **sends nothing when nothing would change**, so the periodic reconcile never
>   rolls your agent on its own. But a rotation does. If the agent runs somewhere
>   you control the process instead, [`seekrit run`](/docs/guides/run) injects the
>   same values with no copy at the platform and no redeploy.

## 1. Create a LangSmith API key

In LangSmith, **Settings → API keys → Create API key**. Prefer a
**workspace-scoped** key (`lsv2_pt_…`): it names its own workspace, so the
connection needs nothing else. An **organization-scoped** key reaches every
workspace in the org, and without a workspace ID the control plane refuses it
with a bare `403`.

```bash
printf '%s' "$LANGSMITH_API_KEY" \
  | seekrit sync connect --name acme-langgraph --provider langgraph-platform
```

That is the whole connection for a US account. Two things can change it:

```bash
# An account in another region — chosen at signup and fixed afterwards.
printf '%s' "$LANGSMITH_API_KEY" \
  | seekrit sync connect --name acme-langgraph --provider langgraph-platform \
      --langgraph-region eu

# An organization-scoped key, which has to say which workspace.
printf '%s' "$LANGSMITH_API_KEY" \
  | seekrit sync connect --name acme-langgraph --provider langgraph-platform \
      --langgraph-tenant 8f1c2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d
```

The region matters more than it looks. LangChain runs the control plane on four
hosts, a key minted in one is **not accepted by another**, and the failure is a
plain `401` — so the wrong region here looks exactly like a bad credential:

| `--langgraph-region` | Control-plane host |
| --- | --- |
| `us` (default) | `https://api.host.langchain.com` |
| `eu` | `https://eu.api.host.langchain.com` |
| `apac` | `https://apac.api.host.langchain.com` |
| `aws-us` | `https://aws.api.host.langchain.com` |

An account created at `smith.langchain.com` is `us`.

> **Note:** **Self-hosted LangSmith.** Pass `--base-url` instead of `--langgraph-region`,
>   pointing at the control plane on your own host — it is served under
>   `/api-host`, e.g. `https://langsmith.acme.com/api-host`. It must be `https:`,
>   because that address carries the API key. Setting both a region and a base URL
>   is refused rather than resolved in seekrit's favour.

## 2. Bind an environment

A deployment has **one** set of secrets, so the deployment is the whole
destination — there is no per-revision or per-graph scope, and no equivalent of
Vercel's production/preview split. A deployment that needs different values is a
different binding.

```bash
seekrit sync verify acme-langgraph --provider langgraph-platform \
  --langgraph-deployment 3970e0fe-8564-4903-9a55-c5f8de49fb8b

seekrit sync enable --connection acme-langgraph --provider langgraph-platform \
  --langgraph-deployment 3970e0fe-8564-4903-9a55-c5f8de49fb8b \
  --app storefront-agent --env production --acknowledge-decryption
```

`--langgraph-deployment` is the deployment UUID from its dashboard URL, or the
`id` from `GET /v2/deployments`; `--app` is the seekrit application the
environment belongs to.

Verify checks the deployment through its **revision list** rather than by
fetching the deployment. Both prove the same three things you can get wrong from
the connection dialog — key valid, workspace reachable, deployment real — but a
revision carries only ids, timestamps, status and source, never a value. A
deployment whose first revision is still building answers with an empty list,
which passes: the deployment is there, and that is the question.

## How a push behaves

- **It reads before it writes.** The array sent is the array the deployment ends
  up with, so seekrit reads the current secrets and writes back
  `(existing − removed) ∪ seekrit`. Sending only seekrit's names would delete
  every environment variable on the deployment that seekrit does not manage.
- **Values you set by hand survive.** A `LOG_LEVEL` added in the dashboard, or
  another team's key, is carried through a push exactly as it was read.
- **A run that would change nothing sends nothing.** This is the one that
  matters here: without it, the reconcile timer would build a new revision of
  your agent every few minutes forever.
- **Only `secrets` is ever sent.** A `PATCH` carrying `source_config`,
  `source_revision_config` or `revision_source` would decide which *code* the
  new revision builds. Omitting them lets the control plane fall back to the
  deployment's own source, so a secrets push can never be the thing that ships
  new application code. `secret_references` — Kubernetes Secret references on
  self-hosted installs — is never sent either.
- **A rejected write is blamed on every name in it**, which is honest here: the
  control plane validates the array before applying it, so a rejected `PATCH`
  leaves the deployment exactly as it was and nothing landed.
- **A value the control plane echoes back in an error is scrubbed** before the
  reason is stored on the run row — including a foreign value the array carried
  through.

## Name and value rules

> **Note:** LangGraph Platform will not accept every name seekrit will. It **reserves**
>   the names it sets itself — `LANGSMITH_API_KEY`, `LANGCHAIN_PROJECT`,
>   `POSTGRES_URI`, `REDIS_URI`, `PATH`, `PORT` and around thirty more. seekrit
>   skips a reserved name rather than sending it, and reports it as a failure
>   against that name alone, because the whole run is one request: one
>   unacceptable name would otherwise take the entire environment down with it.
>   Watch for it if you use a `--prefix`.
> 
> A secret with an **empty value** is failed the same way. The control plane
>   drops one rather than storing it, so a sent empty does not come back on the
>   next read — and seekrit's "nothing changed" check would never agree, which
>   would rebuild your agent on every reconcile tick for as long as the binding
>   existed. Failing the one name is the cheap end of that trade.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `401` on every name | The key was revoked — or the connection names the wrong region, which fails identically | Check the region against the table above, then re-create the connection |
| `403` | An organization-scoped key with no workspace ID, or a key without update permission | Add `--langgraph-tenant`, or use a workspace-scoped key that can update the deployment |
| `404` on the deployment | The deployment name in the ID slot, or the deployment was deleted | Use the UUID from the dashboard URL |
| One name failed, rest landed | The mapped name is reserved by LangGraph, or its value is empty | Rename it (or fix the prefix); seekrit refuses to send it rather than fail the run |
| Every name reported failed at once | The single `PATCH` was rejected | Nothing landed — the control plane validates before applying. Fix the cause and re-run |
| The agent redeploys on every sync | A value really is changing every run — an interpolated reference, or a rotation schedule | Check the run ledger for which name; a stable environment sends no request at all |
| A run fails with "refusing to write" | The control plane returned masked secret values, so writing them back would overwrite real ones | Please report it — the connector needs updating, and it fails loudly rather than destroying your environment |

## See also

- [Third-party sync](/docs/guides/third-party-sync) — the shared model, naming and filtering, deletions
- [Agent sandboxes](/docs/guides/sandboxes) — the other half of agent hosting, where you *do* control the process
- [CLI reference](/docs/reference/cli#third-party-sync) — every `seekrit sync` flag
