@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/get-started/an-agent-in-a-sandbox.md

@@ -0,0 +1,381 @@
+---
+title: An Agent in a Sandbox
+description: A coder Agent fixes a bug in your fork of jr2, in a Sandbox. You push its branch, and approve.
+---
+
+# An Agent in a Sandbox
+
+At the end of this page, a coder [Agent](../reference/glossary.md#agent) has fixed a bug in your fork of jr2. The Agent
+works in a [Sandbox](../reference/glossary.md#sandbox): a pod of its own, with a git checkout of your fork. You go into
+the Sandbox and read the work. You ask for one more change, push the branch by hand, and approve the work.
+
+## Before you start
+
+- Do [A model decides](a-model-decides.md) first. Your [Instance](../reference/glossary.md#instance) `my-instance` has
+  the model of your tab, and `kind-jr2` is the current kubectl context.
+- You need a GitHub account.
+- Open two terminals in `my-instance`. The first terminal shows the run. The second terminal sends commands to it.
+
+## Fork jr2
+
+The Agent works on a [Repo](../reference/glossary.md#repo) that you can push to, so you fork jr2. Your fork holds the
+tutorial fixture, `docs/site/tutorial/greet/`. It is a small Node CLI with one bug, and its test `trims the name` fails.
+
+1. Open `https://github.com/snapwich/jr2`.
+2. Click **Fork**.
+3. Clear **Copy the main branch only**, so that the fork gets the release tags.
+4. Click **Create fork**.
+
+Make sure that the fork has the release tag of your Kit. `<you>` is your GitHub user name. `<version>` is the
+[Kit version](../reference/glossary.md#kit-version): the version of `@jr2/orchestrator` in `package.json`, such as
+`0.4.1`.
+
+1. Open `https://github.com/<you>/jr2/tags`.
+2. Find the tag `v<version>`, such as `v0.4.1`.
+
+If the page shows no tags, delete the fork. Fork again with **Copy the main branch only** cleared.
+
+## Make a token for the fork
+
+The Agent cannot push. You push its branch by hand, so you need a token for your fork. On GitHub, make a fine-grained
+personal access token:
+
+1. Click your profile picture, then **Settings**.
+2. Click **Developer settings**, then **Personal access tokens**, then **Fine-grained tokens**.
+3. Click **Generate new token**.
+4. In **Repository access**, select **Only select repositories**.
+5. Select `<you>/jr2`.
+6. In **Permissions**, set **Contents** to **Read and write**.
+7. Click **Generate token**.
+8. Copy the token.
+
+Keep the token in a safe place. You use it on this page and on the next page.
+
+## Install @jr2/machines
+
+The Kit ships [Machines](../reference/glossary.md#machine) in the package `@jr2/machines`. Install it at the Kit
+version:
+
+```sh
+npm install --save-exact @jr2/machines@<version>
+```
+
+```text
+
+added 1 package, and audited 15 packages in 266ms
+
+3 packages are looking for funding
+  run `npm fund` for details
+
+found 0 vulnerabilities
+```
+
+Your numbers can be different.
+
+## Write the Workflow
+
+The shipped Machine [`task`](../reference/machines.md#task) gives one prompt to a coder Agent in a
+[Workspace](../reference/glossary.md#workspace). Then the run waits at a [Gate](../reference/glossary.md#gate) named
+`review`, until you approve the work. `task` puts the `review` Gate in its body, so the id of the Gate is `body.review`.
+
+`task` cannot know your Repo, and it cannot pay for your model. Thus it leaves two parts
+[Open](../reference/glossary.md#open): its [Repo Slots](../reference/glossary.md#repo-slot) and the model of its coder.
+You bind the two with [`customize()`](../reference/authoring-surface/customize.md).
+
+Make the file `workflows/task.ts`. Replace `<you>` and `<version>` in it:
+
+**Anthropic**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+// `task` leaves two parts Open: its Repo Slots and the model of its coder. This file binds the two.
+// The file name gives the Workflow its name: task.
+export const machine = customize(task, {
+  // One Repo Slot, target: your fork, from the release tag of the Kit that you installed.
+  // Replace <you> with your GitHub user name. Replace <version> with the Kit version.
+  repos: { target: { url: "https://github.com/<you>/jr2.git", ref: "v<version>" } },
+  // The model that the coder Agent uses.
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+});
+```
+
+**Local**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+// `task` leaves two parts Open: its Repo Slots and the model of its coder. This file binds the two.
+// The file name gives the Workflow its name: task.
+export const machine = customize(task, {
+  // One Repo Slot, target: your fork, from the release tag of the Kit that you installed.
+  // Replace <you> with your GitHub user name. Replace <version> with the Kit version.
+  repos: { target: { url: "https://github.com/<you>/jr2.git", ref: "v<version>" } },
+  // The model that the coder Agent uses.
+  agents: { coder: { model: "local/qwen3.6-35b-a3b" } },
+});
+```
+
+- `target` is the name of the Repo Slot. The coder works in the first Repo Slot.
+- `ref` is the release tag. The branch of the Agent starts from it, so each reader of a release starts from the same
+  fixture.
+- The file name gives the [Workflow](../reference/glossary.md#workflow) its name: `task`.
+
+## Converge the Instance
+
+[`jr2 up`](../reference/cli.md#up) converges the Instance with the new Workflow:
+
+```sh
+jr2 up
+```
+
+```text
+…
+seats: workflow "task" — who may send what, per state (ADR-0015)
+  task.working agent:coder: [finish]
+  task.review gate: [approve, request_changes]
+…
+sandbox image "default": building jr2-sandbox-my-instance-default:6389bdf72d50-amd64
+  no USER declared — the pod's uid-1000 fallback applies
+  kind load → cluster "jr2"
+…
+repos: 1 bound Repo(s) — the Orchestrator creates their Repo resources at boot and at each publish (ADR-0069); the cache agent clones on first need (`jr2 status` reports sync state)
+converged — `jr2 run <workflow>` when ready
+```
+
+`task` is the first Workflow of the Instance that has a Workspace. Thus this `jr2 up` also builds the
+[Sandbox Image](../reference/glossary.md#sandbox-image) from `images/default/Dockerfile`, and loads it into the kind
+cluster. If you did not bind an Open part, `jr2 up` stops and prints the `customize()` line that binds it.
+
+## Start the run
+
+In the first terminal, start a run of `task` with [`jr2 run`](../reference/cli.md#run). The prompt tells the Agent what
+to fix and how to check the fix:
+
+```sh
+jr2 run task --input '{"prompt":"In docs/site/tutorial/greet, one test fails. Fix the bug in docs/site/tutorial/greet/src/greet.js. To check your fix, run node --test in docs/site/tutorial/greet. Do not change files outside that folder. Do not run the tests of the repo root."}'
+```
+
+```text
+…
+→ context kind-jr2 / namespace my-instance
+run a7a8fc26-851f-4459-9efb-845389acfda9 (task) — attached
+  → active "placing"
+  → active "provisioning"
+  → active "attaching"
+  → active "running"
+…
+```
+
+The line `run <run id> (task) — attached` gives the run id. Your run id is different. As on the last page, the first
+line of the output, `→ .env:`, shows as `…`. Keep this terminal open. The run does not end until you approve the work.
+
+## Wait for the review Gate
+
+The Sandbox starts, and the coder works. When the coder finishes, the run waits at the `review` Gate. In the second
+terminal, read the status of the run with [`jr2 status`](../reference/cli.md#status). `<run id>` is the run id, or its
+first 4 characters or more:
+
+```sh
+jr2 status <run id>
+```
+
+The status is one line of JSON. While the coder works, `gates` is `[]`. When the run waits at `review`, `gates` holds
+the Gate. Its `gate` is `body.review`, and the line ends with its `meta`:
+
+```text
+…"gate":"body.review",…,"meta":{"summary":"Fixed the \"trims the name\" test failure in docs/site/tutorial/greet. The bug was that the name wasn't being trimmed before constructing the greeting output. Added `.trim()` to the name extraction in src/greet.js, changing `args.find(...) ?? \"world\"` to `(args.find(...) ?? \"world\").trim()`. All 6 tests now pass.","branch":"jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16","worktree":"/work/target/jr2-task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16"}}]}
+```
+
+Run the command again until `gates` holds the Gate.
+
+- `summary` is what the coder says that it did, in the words of the model. Your summary is different.
+- `branch` is the branch that the coder commits on.
+- `worktree` is the folder in the Sandbox that holds the branch. It is
+  [the Worktree](../reference/glossary.md#worktree).
+
+Copy `branch` and `worktree` from your output. The part after `jr2/task-`, here `d8f59a0c-9ea1-43fc-8d0c-b153caf70f16`,
+is the [Instance ID](../reference/glossary.md#instance-id) of the run. `jr2 status` prints it as `instanceId`. It is not
+the run id. Do not make the branch name from the run id. With the Instance token, the drawer of the
+[Console](../reference/glossary.md#console) shows the same `meta`.
+
+If `meta` has a `reason` and no `summary`, the [Turn](../reference/glossary.md#turn) of the coder failed. Send
+`request_changes`, as in [Ask for a change](#ask-for-a-change), and the coder tries again.
+
+## Find the Sandbox
+
+The label `jr2.dev/run` on the Sandbox holds the full run id. A prefix does not work here. Copy the full run id from the
+line `run <run id> (task) — attached` in the first terminal:
+
+```sh
+kubectl -n my-instance get sandboxes -l jr2.dev/run=<run id>
+```
+
+```text
+NAME                      PHASE   ENDPOINT                                              AGE
+ws-a7a8fc26-x-38-oakg23   Ready   http://ws-a7a8fc26-x-38-oakg23.my-instance.svc:8080   5m10s
+```
+
+`ws-a7a8fc26-x-38-oakg23` is the name of the Sandbox. Your Sandbox has a different name. It starts with `ws-` and the
+first 8 characters of the run id. The pod of the Sandbox has the same name. The commands below write it as `<sandbox>`.
+
+## Look inside the Sandbox
+
+Go into the `harness` container of the pod. The Agent's tools run in this container:
+
+```sh
+kubectl -n my-instance exec -it <sandbox> -c harness -- bash
+```
+
+In the Sandbox, go to the fixture in the Worktree. Then run its tests. `<worktree>` is the `worktree` that you copied:
+
+```sh
+cd <worktree>/docs/site/tutorial/greet
+node --test
+```
+
+```text
+✔ greets the world by default (1.172165ms)
+✔ greets a name (0.138615ms)
+✔ shouts (0.117168ms)
+✔ trims the name (0.067037ms)
+✔ prints help (0.642445ms)
+✔ refuses an unknown flag (0.281559ms)
+ℹ tests 6
+ℹ suites 0
+ℹ pass 6
+ℹ fail 0
+ℹ cancelled 0
+ℹ skipped 0
+ℹ todo 0
+ℹ duration_ms 55.318206
+```
+
+Your times are different. Read the commits of the coder. The branch starts at the release tag, so the commits after the
+tag are the commits of the coder:
+
+```sh
+git log --oneline v<version>..HEAD
+```
+
+```text
+1a84393 Fix: trim the name before using it in greet output
+```
+
+Each line is one commit. The commit ids and the messages come from the model. The author of each commit is
+`jr2 Agent <agent@jr2.invalid>`, the default git author that jr2 gives a Sandbox. Then leave the Sandbox:
+
+```sh
+exit
+```
+
+## Ask for a change
+
+In the second terminal, send `request_changes` to the `review` Gate with [`jr2 send`](../reference/cli.md#send).
+`--gate` takes the `gate` value from `jr2 status`. Put your notes in the input:
+
+```sh
+jr2 send <run id> --gate body.review --event request_changes --input '{"notes":"Also add a test that trims the name when you pass --shout."}'
+```
+
+```text
+…
+→ context kind-jr2 / namespace my-instance
+delivered request_changes to gate "body.review" on a7a8fc26-851f-4459-9efb-845389acfda9
+```
+
+The coder continues the same conversation, with your notes as its next prompt. The Sandbox and the branch stay. Run
+`jr2 status <run id>` again until `gates` holds the `review` Gate. The new `summary` tells what the coder changed.
+
+## Push the branch
+
+`task` does not push, and the Agent has no credential to push with. While the run waits at `review`, you push the branch
+from the Sandbox. Go into the Sandbox again:
+
+```sh
+kubectl -n my-instance exec -it <sandbox> -c harness -- bash
+```
+
+In the Sandbox, go to the Worktree. Then push the branch. `<branch>` is the `branch` that you copied:
+
+```sh
+cd <worktree>
+git push origin <branch>
+```
+
+`git push` asks for a user name and a password. Give `<you>` as the user name. Give the token as the password.
+
+```text
+Username for 'https://github.com': <you>
+Password for 'https://<you>@github.com':
+…
+To https://github.com/<you>/jr2.git
+ * [new branch]      jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16 -> jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16
+```
+
+`origin` fetches through the Repo cache of the node, and pushes to your fork. Open your fork on GitHub to see the
+branch. Then leave the Sandbox:
+
+```sh
+exit
+```
+
+## Approve the work
+
+> **Caution**
+>
+> `approve` ends the run and removes the Sandbox. A commit that you did not push is lost.
+
+In the second terminal, send `approve` to the `review` Gate. `approve` takes no input:
+
+```sh
+jr2 send <run id> --gate body.review --event approve
+```
+
+```text
+…
+→ context kind-jr2 / namespace my-instance
+delivered approve to gate "body.review" on a7a8fc26-851f-4459-9efb-845389acfda9
+```
+
+In the first terminal, `jr2 run` prints the end of the run, then the final status as one line of JSON, and stops:
+
+```text
+…
+  → active "teardown"
+  → done "done"
+{"runId":"a7a8fc26-851f-4459-9efb-845389acfda9","workflow":"task",…,"output":{"branch":"jr2/task-d8f59a0c-9ea1-43fc-8d0c-b153caf70f16"}}
+```
+
+## Make sure that the Sandbox is gone
+
+Use the full run id again:
+
+```sh
+kubectl -n my-instance get sandboxes -l jr2.dev/run=<run id>
+```
+
+```text
+No resources found in my-instance namespace.
+```
+
+## What happened
+
+- `task` is a Machine in a Workspace. The run made a Sandbox for the Workspace and cloned your fork into it. It cut the
+  branch from the release tag, in a Worktree in `/work/target/`. See [Workspaces](../concepts/workspaces.md).
+- `task` left its Repo Slots and the model of its coder Open. `customize()` bound them where you registered the
+  Workflow, and `jr2 up` refuses a Workflow with an Open part. See [Composition](../concepts/composition.md) and
+  [ADR-0054](../reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md).
+- The `review` Gate kept the Sandbox while the run waited. `request_changes` sent the coder back to the same
+  conversation. `approve` ended the run, and the end of the Workspace removed the Sandbox. See
+  [Gates](../concepts/gates.md) and [ADR-0012](../reference/decisions/0012-workspace-wrapper-machine.md).
+- You used `kubectl exec` to go into the Sandbox. The guide [Look inside a Sandbox](../guides/look-inside-a-sandbox.md)
+  gives the same commands.
+- You pushed by hand, because `task` does not push. On the next page, a Machine pushes the branch with an
+  [Effect](../reference/glossary.md#effect).
+
+## Next
+
+[Have your Assistant write a Machine](have-your-assistant-write-a-machine.md)

package/docs/get-started/connect-a-model.md

@@ -0,0 +1,248 @@
+---
+title: Connect a model
+description: Add a model to the Instance, with its key or its address in .env, and converge the Instance again.
+---
+
+# Connect a model
+
+At the end of this page, the config of your [Instance](../reference/glossary.md#instance) names a model. `jr2.config.ts`
+names its key or its endpoint, `.env` holds the value, and the cluster has the new config. The next page gives the model
+its first task.
+
+## Before you start
+
+Do [Create an Instance](create-an-instance.md) first. The Instance `my-instance` must be in the kind cluster.
+
+Choose a tab. Choose Anthropic for a model of the Anthropic API. Choose Local for a model that you serve on a computer
+on your network. Each page after this one uses the model of the tab that you choose.
+
+**Anthropic**
+
+You need an Anthropic API key. Make one on the [Anthropic website](https://console.anthropic.com/).
+
+**Local**
+
+You need a computer that can serve Qwen3.6-35B-A3B with a context window of 65536 tokens. It can be the computer that
+runs kind, or a different one on your network. Install one of these two servers on it:
+
+- [vLLM](https://docs.vllm.ai/en/latest/getting_started/installation/)
+- [llama.cpp](https://github.com/ggml-org/llama.cpp/blob/master/docs/install.md)
+
+## Add the model to jr2.config.ts
+
+**Anthropic**
+
+Open `jr2.config.ts`. Find the line that starts with `// secrets:`. Remove the `//`. Keep the other lines and their
+comments. This is the result. Its comments are shorter than the comments in your file:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  git: {
+    // The credentials that the cluster uses to clone and push. The token comes from JR2_GIT_TOKEN in .env.
+    credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }],
+  },
+  // The model key. jr2 up gives it only to the Custodian of each pod whose Agents use Anthropic.
+  secrets: [{ name: "ANTHROPIC_API_KEY", value: process.env.ANTHROPIC_API_KEY }],
+});
+```
+
+The `secrets` line gives jr2 the value of `ANTHROPIC_API_KEY` from `.env`. An [Agent](../reference/glossary.md#agent)
+that names an `anthropic/` model uses this key.
+
+**Local**
+
+Open `jr2.config.ts`. Add the `harness` entry after the `git` entry. Keep the other lines and their comments. This is
+the result. Its comments are shorter than the comments in your file:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  git: {
+    // The credentials that the cluster uses to clone and push. The token comes from JR2_GIT_TOKEN in .env.
+    credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }],
+  },
+  harness: {
+    // An OpenAI-compatible endpoint, such as vLLM or llama.cpp. An Agent names its model as local/<model>.
+    provider: {
+      id: "local",
+      api: "openai-completions",
+      // An address that a pod can reach, from .env. With no apiKey, plain http:// is permitted.
+      baseUrl: process.env.LOCAL_MODEL_URL ?? "",
+      // The key is the name that the endpoint gives for GET /v1/models. The limits agree with the server.
+      models: { "qwen3.6-35b-a3b": { contextWindow: 65536, maxTokens: 8192 } },
+    },
+  },
+});
+```
+
+The entry adds a custom provider with the id `local`. An [Agent](../reference/glossary.md#agent) names a model of this
+provider as `local/<model>`, such as `local/qwen3.6-35b-a3b`. `<model>` is the name that the endpoint gives for
+`GET /v1/models`.
+
+The [config reference](../reference/config.md#secrets) gives each field of `secrets` and of
+[`harness.provider`](../reference/config.md#harness-provider).
+
+## Put the value in .env
+
+**Anthropic**
+
+Make the file `.env` in `my-instance`. Put this line in it, with your key in place of `<your key>`:
+
+```text
+ANTHROPIC_API_KEY=<your key>
+```
+
+**Local**
+
+Make the file `.env` in `my-instance`. Put this line in it:
+
+```text
+LOCAL_MODEL_URL=http://<address>:8000/v1
+```
+
+`<address>` is an address of the server computer that a pod can reach, such as its LAN address. Do not use `localhost`.
+In a pod, `localhost` is the pod itself.
+
+The jr2 CLI reads `.env` before each command, and names each key that it takes from `.env`. A variable that you set in
+your shell has priority over `.env`. Do not put `.env` in git: the `.gitignore` that `jr2 init` wrote keeps it out.
+
+## Start the model server
+
+**Anthropic**
+
+There is no server to start. Go to the next step.
+
+**Local**
+
+On the server computer, start one of the two servers. Each command serves the model as `qwen3.6-35b-a3b`, on port 8000,
+on all addresses (`0.0.0.0`). The pods cannot reach a server that listens only on its loopback address.
+
+To start llama.cpp, run:
+
+```sh
+llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q6_K_XL --alias qwen3.6-35b-a3b --no-mmproj \
+  --host 0.0.0.0 --port 8000 --jinja -c 65536 \
+  --temp 0.6 --presence-penalty 1.0 -ctk q8_0 -ctv q8_0 -fa on
+```
+
+`--jinja` lets the model call tools. `--temp 0.6` and `--presence-penalty 1.0` are the sampling settings for Qwen.
+`-ctk q8_0 -ctv q8_0 -fa on` make the KV cache smaller, so that 65536 tokens fit in memory.
+
+To start vLLM, run:
+
+```sh
+vllm serve Qwen/Qwen3.6-35B-A3B --served-model-name qwen3.6-35b-a3b \
+  --host 0.0.0.0 --port 8000 --max-model-len 65536 \
+  --enable-auto-tool-choice --tool-call-parser qwen3_coder
+```
+
+`--enable-auto-tool-choice` and `--tool-call-parser` let the model call tools.
+
+With each of the two servers, the model must make tool calls. `jr2 up` asks the model for one tool call before it
+converges, and stops when the model does not make one.
+
+## Check the model server
+
+**Anthropic**
+
+There is no server to check. Go to the next step.
+
+**Local**
+
+From the computer that runs kind, run:
+
+```sh
+curl http://<address>:8000/v1/models
+```
+
+The server sends a JSON object. This object is from vLLM. llama.cpp sends different fields:
+
+```text
+{"object":"list","data":[{"id":"qwen3.6-35b-a3b","object":"model","created":1792819567,"owned_by":"vllm",…,"max_model_len":65536,…}]}
+```
+
+The `data` list in the JSON that the server sends has the id `qwen3.6-35b-a3b`. If `curl` cannot connect, make sure that
+the server listens on `0.0.0.0`. Also make sure that no firewall stops port 8000.
+
+## Converge the Instance again
+
+Run:
+
+```sh
+jr2 up
+```
+
+`jr2 up` reads the new config and converges the cluster again. The namespace is there, so it does not ask this time.
+
+**Anthropic**
+
+```text
+→ .env: ANTHROPIC_API_KEY
+jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
+…
+warning: secrets[0] (ANTHROPIC_API_KEY) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect names it (ADR-0059, ADR-0068)
+…
+converged — `jr2 run <workflow>` when ready
+```
+
+The warning is correct for now. No [Workflow](../reference/glossary.md#workflow) has an Agent that names an `anthropic/`
+model, so no pod gets the key.
+
+The next page adds a Workflow with an Agent that names the model. On the next page, `jr2 up` gives the key to the
+[Custodian](../reference/glossary.md#custodian) of the pod where the Agent works. Then it asks the model for one tool
+call through a Custodian that holds the key, before it converges. It is the first `jr2 up` that reaches the model.
+
+**Local**
+
+```text
+→ .env: LOCAL_MODEL_URL
+jr2 up — instance "my-instance" → context kind-jr2 / namespace my-instance
+…
+provider: http://<address>:8000/v1 configured, but no carried Agent names a "local/…" model — skipped
+…
+converged — `jr2 run <workflow>` when ready
+```
+
+`jr2 up` skips the check of the provider for now. No [Workflow](../reference/glossary.md#workflow) has an Agent that
+names a `local/` model, so there is no model to check.
+
+The next page adds a Workflow with an Agent that names the model. On the next page, `jr2 up` checks the endpoint before
+it converges. It is the first `jr2 up` that reaches the model.
+
+`jr2 up` published the new `jr2.config.ts` to the [Orchestrator](../reference/glossary.md#orchestrator) in the
+[Assembly](../reference/glossary.md#assembly). The Orchestrator loaded it with no restart, so the port forward of
+[Create an Instance](create-an-instance.md) stays open.
+
+## What happened
+
+**Anthropic**
+
+The API key is a [Held secret](../reference/glossary.md#held-secret). In this Instance, `jr2 up` gives its value only to
+the Custodian of each pod whose Agents use an `anthropic/` model. The Custodian is a container next to the
+[Harness](../reference/glossary.md#harness) container, where the Agent works. The Harness container holds only a
+[Stand-in](../reference/glossary.md#stand-in): a value that is worth nothing outside the pod. The Custodian puts the
+real key into each request to the Anthropic API. Thus the Agent never holds the key
+([ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md)).
+
+To use a gateway or a different hosted provider, read
+[Use a hosted provider or a gateway](../guides/use-a-hosted-provider.md).
+
+**Local**
+
+`harness.provider` adds a custom provider to the [Harness](../reference/glossary.md#harness). The Harness speaks to it
+over the OpenAI chat completions API
+([ADR-0018](../reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)). When an Agent
+names a `local/` model, `jr2 up` checks the endpoint from a pod in the cluster before it converges. It asks for the list
+of models, and then for one tool call. If the check fails, `jr2 up` stops and says why.
+
+This endpoint has no key, so jr2 permits plain `http://`. To add TLS and a key, read
+[Use a local model](../guides/use-a-local-model.md).
+
+[Secrets and trust](../concepts/secrets-and-trust.md) explains where each secret goes, and who can use it.
+
+## Next
+
+[A model decides](a-model-decides.md).