@orchestraworks/cli 0.5.1 → 0.5.3

package/skills/orchestra-fdk/references/authoring.md

@@ -103,6 +103,21 @@ entrypoint decides what answers. Omit `harness`, or misspell it, and synth fails
 a message naming the five; there is no default, because guessing which one an author meant would pick a
 different program than the one they wanted.
 
+### Every agent's instructions start with an Attribution section
+
+The starter's agents start their instructions with it. When you write an agent of your own, start its
+instructions with the same section, with the agent's display name and slug filled in:
+
+```
+## Attribution
+You are <agent display name>. Mark the work you produce as yours:
+- every commit message and pull request description ends with
+  Co-Authored-By: <agent display name> <<agent-slug>@agents.orchestraworks.ai>
+- every comment and tracker edit ends with one line: — <agent display name>, Orchestra
+```
+
+A person who reads a commit, a pull request, a comment or a tracker edit then sees which agent made it.
+
 ### Platform skills are attached by id
 
 An agent uses a platform skill only when its `skills` list names it: `Skill.fromId(factory, "skill_<key>")`
@@ -516,7 +531,7 @@ const claudeSignIn = new Secret(factory, "claude-sign-in", {
 });
 
 // …in the Environment's props:
-env: { CLAUDE_CODE_OAUTH_TOKEN: "placeholder", ANTHROPIC_API_KEY: "" },
+env: { CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder", ANTHROPIC_API_KEY: "" },
 egress: EgressPolicy.allowAll()
   .allow("claude-sign-in", { hosts: ["api.anthropic.com"], priority: 300, credential: claudeSignIn }),
 ```
@@ -604,6 +619,106 @@ which the harness would otherwise send instead.
   (the recipe supplies the headers), or use `bearer(header, secret)` / `basic(...)` / `header(...)`
   for one-header bindings, or `inject(secret, recipe)` for a binding-owned recipe.
 
+## How the agents reach a model
+
+Ask the person which of three ways they want, and walk them through its steps once.
+
+**1. Subscription: their own Claude or Codex sign-in.** The person makes the sign-in in a real terminal
+on their own computer; run from your shell, its browser step hangs. Never read or copy a value yourself.
+
+- **Claude: a long-lived token in a Secret, the recommended way.** `claude setup-token` prints an
+  `sk-ant-oat…` token made for servers. It lasts about a year, and nothing on a machine renews or revokes
+  it, so it needs no shared `/home`. The person copies it and saves it to a file only they can read,
+  without pasting it into a chat: `umask 077 && pbpaste | tr -d '\n' > <file> && pbcopy </dev/null`.
+  At apply, the shell exports it from that file into the variable the Secret reads. Declare the Claude
+  sign-in recipe (§ Secrets are recipes, never values): a `Secret`, an egress rule that allows
+  `api.anthropic.com` and sets `Authorization: Bearer ${secret}` with `x-api-key` removed, and, in the
+  environment's `env`, `CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder"` and an empty
+  `ANTHROPIC_API_KEY`. Turn `enableModelGateway` off for the agent. The machine holds only the
+  placeholder; the edge adds the token. Copying the renewing credentials file instead is the fallback,
+  and follows the ChatGPT sign-in steps below.
+- **Codex: a personal access token, where the workspace allows one.** A ChatGPT Business or Enterprise
+  member creates it at chatgpt.com/admin/access-tokens, once the workspace owner allows access tokens,
+  and chooses how long it lasts, such as 7 to 90 days. Codex never renews it, so it needs no shared
+  `/home`; the person supplies a new one before it expires. It begins `at-` and goes in
+  `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`, which outranks a ChatGPT sign-in or an API key beside
+  it. On their own computer, `codex login --with-access-token` reads the same token from standard input.
+- **Codex otherwise: a separate ChatGPT sign-in on a shared `/home`.** The other long-lived choice is an
+  OpenAI API key, billed by use rather than by the subscription (option 3).
+  1. **Make a separate sign-in, never a copy of the local one:** `mkdir -p <dir> && CODEX_HOME=<dir>
+     codex login`, with `--device-auth` only on a machine with no browser. Its tokens in
+     `<dir>/auth.json` go in the `ORCHESTRA_WORKER_CODEX_` variables below, or a setup step writes the
+     file.
+  2. **Put it on a shared `/home`.** Give the environment a durable `/home` volume, shared by every
+     machine that uses the sign-in, so one file renews for all of them. Separate copies fight: each
+     renewal replaces the refresh token, so the first copy to renew signs out the others. Two machines
+     that renew in the same second can still sign each other out; then make a new separate sign-in.
+     Remove the variables after the first machine starts, or each new machine writes the old token back.
+  3. **Never sign in again in the default folder after the copy.** A new `codex login` in `~/.codex`
+     revokes the cloud copy, and every machine then answers "refresh token was revoked". If it
+     happened, make a new separate sign-in.
+- **Keep a Codex sign-in off an agent that uses the model gateway.** With a ChatGPT sign-in or a personal
+  access token, Codex compresses its requests, and the gateway refuses them with `model_not_found`, a
+  known issue. Give such an agent the subscription directly, with `enableModelGateway` off, or keep the
+  homes apart.
+
+**2. Model gateway: Orchestra provides the key.** One endpoint reaches OpenAI, Anthropic and open-source
+models, on the organization's credits. The person can also bring their own provider key to the gateway:
+`orchestra fdk init --model-key anthropic` (or `openai`) declares a `ModelProviderKey`, which the gateway uses for
+that provider's calls. The gateway also routes models: `orchestra model-configs` sets which providers serve a
+model and in what order, so a call falls back to the next one when a provider is down, and
+`orchestra model-aliases` gives a model a name of the organization's own, such as `default`, that one change
+points elsewhere.
+
+**3. Own API key via the vault.** Their Anthropic or OpenAI API key is a platform `Secret`, added at the
+network edge on calls straight to the provider, with no gateway in between, and nothing to sync, because
+an API key does not renew. Declare it as the Claude sign-in recipe (§ Secrets are recipes) does, with the provider's own
+header, and leave `enableModelGateway` off in the agent's model settings:
+
+```ts
+const anthropicKey = new Secret(factory, "anthropic-api-key", {
+  value: SecretValue.fromEnv("ORCHESTRA_FDK_ANTHROPIC_API_KEY"),
+  injection: { headers: [{ name: "x-api-key", value: "${secret}" }] },
+});
+// …in the Environment's props:
+egress: EgressPolicy.allowAll()
+  .allow("anthropic", { hosts: ["api.anthropic.com"], priority: 300, credential: anthropicKey }),
+```
+
+For OpenAI, inject `authorization: Bearer ${secret}` on `api.openai.com`. Recommend this over a
+subscription when the person has an API key: there is no file to copy and no shared `/home`.
+
+### The subscription variables
+
+The worker writes each value into the file the harness reads, once per machine start, and hands none of
+these variables to the harness. pi can also run on the provider you name.
+
+| Variable | claude | codex | pi |
+|---|---|---|---|
+| `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`: a `claude setup-token` token as a worker setting, in plain text; the Claude sign-in recipe's Secret is the recommended way | yes | — | yes |
+| `ORCHESTRA_WORKER_CLAUDE_ACCESS_TOKEN` and `ORCHESTRA_WORKER_CLAUDE_REFRESH_TOKEN`, plus `ORCHESTRA_WORKER_CLAUDE_EXPIRES_AT` in milliseconds if you have it: a renewing Claude sign-in | yes | — | yes |
+| `ORCHESTRA_WORKER_OPENAI_API_KEY` | — | yes | yes |
+| `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`: a Codex personal access token, which outranks the other Codex rows | — | yes | — |
+| `ORCHESTRA_WORKER_CODEX_ID_TOKEN`, `ORCHESTRA_WORKER_CODEX_ACCESS_TOKEN`, `ORCHESTRA_WORKER_CODEX_REFRESH_TOKEN` and `ORCHESTRA_WORKER_CODEX_ACCOUNT_ID` (`tokens.account_id`, which Codex needs to renew): a ChatGPT sign-in | — | yes | — |
+| `ORCHESTRA_WORKER_PI_PROVIDER`: pi's `defaultProvider`, such as `anthropic` or `openai` | — | — | yes |
+
+You can also bake the harness's own sign-in or settings file into the image with the setup script. With
+no variable set, the worker leaves a value already in that file alone. For pi, your own
+`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in `env` still works: the worker then leaves that provider's
+placeholder out of pi's sign-in file, which pi would otherwise read first, and holds back the image's
+`ANTHROPIC_OAUTH_TOKEN` placeholder beside your own `ANTHROPIC_API_KEY`.
+
+- **The value is plain text.** `env` is stored unencrypted, and an environment read returns it. Anyone
+  who can read the environment can read its setup script.
+- **Allow the sign-in hosts with no credential bound**: `platform.claude.com` for a copied Claude
+  credentials file, `api.openai.com` for an OpenAI key, `auth.openai.com` and `chatgpt.com` for ChatGPT. A
+  rule that binds a credential on one of these hosts replaces your sign-in on every call.
+- **Name pi's provider when the model is not a Claude one.** pi runs the agent's model under its
+  `defaultProvider`, which `ORCHESTRA_WORKER_PI_PROVIDER` sets; with no variable, pi keeps the image's
+  `anthropic` or the provider you configured. The platform never picks it from the model.
+- **On a Mac outpost, Claude Code reads the login Keychain first.** Sign out of Claude Code there, or
+  use `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`, which Claude Code reads before the Keychain.
+
 ## Egress: apply the bundles, hand-write the rest
 
 An environment's `egress` is a policy you build up from one of **two starting points**:
@@ -977,9 +1092,9 @@ cookie your app sets must carry `SameSite=None; Secure; Partitioned`, or the bro
 frame and your app's own sign-in or session state is lost on each load. The platform's own access
 cookie is already set this way, and your app never sees it.
 
-### Typed flows: `user-grants grant` and `sessions wait`
+### Typed flows: `user-grants grant`, `sessions wait` and `sessions tail`
 
-Two commands stay hand-shaped, because the orchestration is the value a bare generated call would
+Three commands stay hand-shaped, because the orchestration is the value a bare generated call would
 drop. Both are platform commands — they read and write the live factory, not your code.
 
 ```bash
@@ -1004,6 +1119,18 @@ taking no more messages), which settles too. `--interval` and `--timeout` are yo
 any settlement (the printed state
 carries the outcome) and non-zero only on a timeout or a failed call.
 
+```bash
+orchestra sessions tail session_01abc --until-settled
+```
+
+Prints each item of the session as it is saved: a reply line by line as it grows, a tool call as one
+line, printed again when its status changes. With `--output json` it prints each item once, as one
+JSON line, when the item can no longer change. It starts with the items that
+already exist; `--after <item id>` starts after that item instead. While a turn runs, each read waits
+on the platform for the next saved output, so the command does not poll on a timer. `--until-settled`
+exits once the turn has ended and prints the session's status, with exit 0 whatever the status, as
+`sessions wait` does. Without it, the command follows the session until Ctrl-C.
+
 ### The backup: `orchestra api`
 
 `orchestra api GET "/sessions?limit=5"` makes a raw authenticated call — exactly `gh api`'s role — through

package/skills/orchestra-fdk/references/environment.md

@@ -1,7 +1,7 @@
 # Port a codebase's setup to Orchestra machines
 
-Step 8 of the orchestra-fdk skill, "Set up the machines", sends you here, and so does its step 3 for a new
-environment in an existing factory. When you finish, go back to the step that sent you.
+Phase 4 of the orchestra-fdk skill, "Build", sends you here, for a new factory and for a new environment in
+an existing factory. When you finish section 6, go back to phase 4 for the apply.
 
 An agent can fix, test or show a codebase only if its machine can install and run it. You find out how
 this team sets up their code, prove it on this computer first, write it into the factory, and apply it.
@@ -319,7 +319,7 @@ Orchestra Secret, and our network edge adds it to each model call, so no machine
 
 - For the gateway, `apply` creates the gateway key and its secret. The starter already declares them.
 - For a subscription token or a provider key, declare a Secret and a rule that adds it on the provider's
-  host, as step 6 of the orchestra-fdk skill says (orchestra skill, sections 6 and 7).
+  host, as phase 2 of the orchestra-fdk skill, "The model route", says (orchestra skill, sections 6 and 7).
 
 Ask the developer to revoke the `local-dev` gateway key, at **Settings › Gateway keys**, when local work is
 done.
@@ -332,6 +332,116 @@ fails and why. Report which tests ran and which could not. Then run `orchestra l
 Ask the developer to confirm the path you recommend, with your question tool. The mode you proved points
 to the path, as the table in section 2 says: a container machine to A, the host outpost to B.
 
+### The machine's runtime, by operating system
+
+An environment's `platform` is `{ os, arch, runtime }`, set when the environment is created. `runtime` never
+changes. On a provisioned environment it is `microvm` (the default) or `vm`. An enrolled environment is
+`host`: the team's own machine, as it is, with no network rules of ours.
+
+The setup script runs once, as root or as the machine's service account, on each new machine, before the
+agent arrives and before any code is cloned. It is at most 64 KiB. It has 10 minutes. The limit is fixed for
+now, and an environment cannot raise it. A worker that starts again on the same
+machine reuses the result it kept, and does not run the script again.
+
+#### Linux
+
+Most code: web, backend, mobile build tools, anything that runs in Docker.
+
+| Runtime and where it runs | Base image: what's in it | Sizes | Disks and shared volumes | Setup script | Home and continuity | Requirements and limits |
+|---|---|---|---|---|---|---|
+| `microvm`: a Kata micro VM on Kubernetes, amd64. `vm`: an EC2 Ubuntu VM, amd64 or arm64 | `microvm`: Debian with Node 24, Java 21 and 25, Python 3, a C and C++ build toolchain, git, the GitHub CLI `gh`, and Docker with Compose and Buildx (not started until the setup script starts it). `vm`: Ubuntu 24.04 with Node 24, git, and rootless Docker with Buildx, which runs from boot as the agent's user. The VM has no Java and no Compose plugin: install the ones the code needs in the setup script. Both carry the worker and the `claude`, `codex`, `pi` and `script` harnesses | `microvm`: 0.5, 1, 2, 4, 8, 16 or 32 CPU. `vm`: 2, 4 or 8 CPU. 2 GB of memory per CPU | `vm`: a 40 GiB root disk. Up to four extra disks (`disks`), such as `/var/lib/docker` and `/work`. Shared volumes (`volumeMounts`) on EFS, which every machine of an environment can mount together | Bash, run with `bash -e`. One exit code per step | A volume at `/home` keeps the agent's home across machines. Without it, nothing in `/home` outlives the machine | No Windows or macOS programs. A kernel of its own, an Android device or nested virtualization needs `vm` |
+
+#### Windows
+
+Code that builds or runs only on Windows: .NET Framework, WinForms, WPF, IIS, Windows-only tools.
+
+| Runtime and where it runs | Base image: what's in it | Sizes | Disks and shared volumes | Setup script | Home and continuity | Requirements and limits |
+|---|---|---|---|---|---|---|
+| `vm`: an EC2 Windows Server VM, amd64. Set `platform: { os: "windows", arch: "amd64", runtime: "vm" }` | Our image only: Windows Server 2025 Core, Node 24, Docker for Windows containers with the Containers feature, the worker, the `orchestra` command, and the `claude`, `codex`, `pi` and `script` harnesses. No git: install it in the setup script. A hosted Windows machine cannot start from another image | 4 or 8 CPU, 2 GB of memory per CPU | The image's 100 GiB root disk. No extra disks: remove `disks`. Shared volumes: not stated | PowerShell 5.1, run as the machine's service account. One exit code per step. Template: "A Windows setup script" below | The machine is parked when idle and keeps its disk, so the home (`C:\sf\home`) and `C:\work` stay. The setup script runs once per machine | Docker runs Windows containers only, for administrators only. A machine takes up to 15 minutes to start the first time |
+
+**Windows in three stages.** Guide a Windows team through these stages, in order. Write the stage you plan
+into `orchestra-factory-notes.md`.
+
+1. **Start on hosted Windows, with our image.** This proves the factory works, with nothing to run in the
+   team's own cloud. The setup script installs what fits in its 10 minutes: Git, and the small tools. A
+   larger toolchain, such as Visual Studio Build Tools or an old SDK, goes in the agent's first turn. The
+   machine is parked when idle and keeps its disk, so the next turn finds the toolchain installed. The agent
+   runs the install in the turn and waits for it: a park stops the VM and kills an install still running.
+   The machine is deleted after `ttl`, 2 hours by default, and a new one starts without the toolchain.
+2. **Then move to the team's own Windows image, through a compute provider in their cloud.** The benefit:
+   each machine starts with the whole toolchain installed, with no setup limit, and the team's licenses,
+   such as Visual Studio's, stay in their own image. The Launcher, the program the team runs in their
+   cloud, starts Windows VMs from the image its environment names. The Launcher runs on Azure (the
+   orchestra skill, section 18). The team bakes the image on Windows Server 2025 and adds their own
+   toolchain: git, MSBuild and .NET are theirs to install. Windows 11 is not supported, and a plain
+   captured Windows VM does not register. The image must contain these three parts:
+   - The worker's release package, for example at `C:\ProgramData\sfdk\worker\package`.
+   - The worker's Windows service, `SfdkWorker`. It runs `worker.exe run --root C:\ProgramData\sfdk\worker
+     --service` as LocalSystem. It is demand-start (`Manual`), not automatic. On a failure it restarts
+     three times, 2 seconds apart, and a clean stop with a non-zero exit code counts as a failure.
+   - The startup task `orchestra-azure-userdata`. It runs `azure-userdata.ps1` as SYSTEM at each boot
+     (`AtStartup`). The script writes the files that the VM's startup data carries, then starts
+     `SfdkWorker`.
+
+   Our image builds the same parts: `install-vm-runtime.ps1` and the image template
+   `infra/packer/azure-windows-runtime.pkr.hcl`. Under a Launcher, the image needs no WinDivert, no
+   redirect firewall rule, no Docker, no Node and no preinstalled harness: a harness installs itself on
+   its first turn, in about 60 seconds. Credentials are the team's to set on the VM (part C, "Tokens on a
+   compute provider's machines"). Our own image is in a public Azure gallery:
+   `/CommunityGalleries/orchestraworks-881a796f-0a84-4be1-af80-0a38564a406a/Images/runtime-win/Versions/0.0.136`
+   (Gen2). An environment that names no image boots its `Versions/latest`. Not released yet: a one-command
+   installer for a team's own image, the Launcher on AWS, and a team's own image on hosted Windows.
+3. **Then keep machines ready, for speed.** `standbyCapacity` on the agent (`Agent` in the kit) keeps
+   `count` machines started, set up and with the agent installed, on a schedule or always. A new
+   conversation then starts at once, with no wait for a Windows first boot. The platform refuses it only
+   for an enrolled environment or a `custom` harness, so it applies to hosted Windows and to a compute
+   provider. Proven on a compute provider's Windows VM: a new conversation got a ready machine, and its
+   turn started in 3.5 seconds. A standby minute is billed: the plan page shows the price.
+   `npx orchestra agents get <agent>` shows `standbyStatus`: how many machines are ready now, and why
+   fewer when that is so.
+
+#### macOS
+
+Code that needs Xcode, the iOS Simulator or another Apple tool.
+
+Not released yet: Orchestra launches no Mac. A Mac works only as the team's own enrolled machine
+(`host`), with the worker installed on it, no network rules of ours and no keys added at the edge. Agree it
+with the Orchestra team first (the orchestra skill, section 18).
+
+#### A custom image
+
+A team's own image, when the stock image plus a setup script is too slow or cannot hold the toolchain.
+
+- Build it `FROM` our runtime image, so it keeps the worker and the harnesses. The public name is
+  `public.ecr.aws/orchestraworks/runtime` (until AWS approves that alias: `public.ecr.aws/z8d3m6s5/runtime`).
+  Pin it by digest; the Orchestra team gives the current one.
+- Push it to the team's own registry. `Image.fromBuild` builds and pushes it at apply. The environment names
+  a pull key Secret in `imagePullCredential` (`provisionSpec.imagePullSecretId` on the platform), made with
+  `SecretValue.registryCredential(<user>, <password>)` or `SecretValue.ecrCredential(<key id>, <secret>)`.
+  The platform reads it at each machine create, and never gives it to the agent. The bug-fix starter's
+  `main.ts` shows the code.
+- Not released yet: a registry hosted by Orchestra.
+- A custom image applies to `microvm`. An EC2 VM starts from our machine image, not from a container image.
+
+#### On this computer
+
+`orchestra local` runs Linux containers only, on Docker Desktop, OrbStack or Docker Engine. On an
+Apple-silicon Mac it runs an `amd64` environment natively as `arm64` when the image carries that pair, and
+never by emulation. Docker set to Windows containers is refused.
+
+A Windows agent runs locally only as an enrolled machine: `orchestra outpost up --agent <id>` on a Windows
+PC, against the local environment (section 4, "Host outpost"). Use it to work out the build, run and test
+commands before the cloud.
+
+Locally the network edge does nothing: no egress rule is enforced, no key is added, and no certificate is
+re-signed. The cloud proves those.
+
+#### Which to pick
+
+Pick `microvm` when the code runs on Linux, with or without Docker. This is most code.
+Pick `vm` when the code needs Windows, an Android device or a kernel of its own.
+Pick `host` when the code must run on the team's own machine, such as a Mac.
+
 ### A. Containers on Linux
 
 Choose A when the code and its services run on Linux, in Docker, Docker Compose, or a setup script. Most
@@ -349,7 +459,7 @@ agent can run the team's own `docker compose up` unchanged.
    machine's processes, the agent included, read every value.
 3. Put each dev server's port in `PORTS`, with a short name. The agent can then show the app at a
    *machine endpoint*, a web address that only signed-in members of the organization can open.
-4. Write the app's own settings files (`.env.local`) into the Set up item's instructions, because the code
+4. Write the app's own settings files (`.env.local`) into the Set up item's description, because the code
    is not on the machine when the setup script runs. Put only local or test values there. A real secret
    becomes a Secret plus a rule that adds it.
 5. Choose the size by what CI uses for the same work. The template's sizes are fixed per agent: lg is
@@ -358,6 +468,28 @@ agent can run the team's own `docker compose up` unchanged.
    the inner Docker's images across machine starts (next part).
 7. Not released yet: `workingDirectory`, the folder where every conversation starts. Today each agent clones
    or uses its code under `/work` in its own first turn, as the starter's agents do.
+8. To keep the agent's home, such as a harness sign-in, across machines, mount one volume at `/home` on
+   every environment that shares it. Make the volume once with `npx orchestra volumes create`, then add
+   `volumeMounts: [{ volume: Volume.fromSlug(factory, "<slug>"), mountPath: "/home" }]`. Without it,
+   nothing in `/home` outlives the machine.
+
+#### Network
+
+Egress starts open, and stays open for the first run: `EgressPolicy.allowAll()`. Any host is reachable, and
+only the hosts that need a key, such as the model gateway, have rules that add one. Never close it while the
+factory is being set up.
+
+Tightening is a later, optional step, after the factory works and the developer asks for it:
+
+1. Start from `EgressPolicy.denyAll()`. A host that no rule allows is refused.
+2. Add `applyPreset(egressPreset.softwareDevelopment())`: package and container registries, and reads
+   from common services, with no key.
+3. Keep `routeModelsViaGateway(...)` or the model key's rule, and every token or connection rule.
+4. Add one `allow` rule for each other host the agents reach, with `priority: 100` and the methods it needs.
+
+Prove the closed list on Orchestra's cloud, not locally: a local run enforces no egress rule ("On this
+computer" above). Apply the tightened policy, then ask an agent to run the build and the tests once on a cloud
+machine. A refused host shows as `destination is not allowed` (`troubleshooting.md`).
 
 #### Setup script or a baked image
 
@@ -392,27 +524,152 @@ Choose B when the code needs a particular kernel or operating system.
 
 - **Windows:** possible. Set `platform: { os: "windows", arch: "amd64", runtime: "vm" }` on the
   environment. A Windows machine is a full EC2 virtual machine with 4 or 8 CPU. Docker data disks are not
-  available on Windows, so remove `disks` and the Docker setup. The Linux `setup.sh` cannot run there. Ask the Orchestra team
-  how a setup script runs on Windows before you rely on one.
+  available on Windows, so remove `disks` and the Docker setup. The Linux `setup.sh` cannot run there: write
+  a PowerShell script from "A Windows setup script" below. Follow "Windows in three stages" in section 5.
 - **Linux on a full VM:** possible with `runtime: "vm"`, at 2, 4 or 8 CPU.
 - **macOS:** only as the team's own Mac, enrolled with the worker. Say what that needs before you offer it
   (the orchestra skill, section 18), and agree it with the Orchestra team first.
 
-### C. The team's private network
-
-Choose C when development needs services or data inside their VPN or their own cloud.
-
-Orchestra's machines cannot reach a private network today. The planned answer is the *Launcher*, which
-runs machines inside the team's own cloud; it does not exist yet, and there is no Azure support. Tell the
-developer:
-
-- what their code needs from the private network, host by host;
-- that this needs a later Orchestra release, or one of their Macs or Linux servers enrolled as a machine
-  (the orchestra skill, section 18);
-- that they can still see a first fix today on the todo sample, or on the parts of the code that need no
-  private service.
-
-Write down what is missing and stop here. Report it to the developer, and go back to the orchestra-fdk skill.
+### A Windows setup script
+
+Tried by us: not yet.
+
+A Windows machine runs the setup script with PowerShell 5.1 (`powershell -NonInteractive -NoProfile
+-ExecutionPolicy Bypass -File setup.ps1`), as the worker's service account, once per machine. A parked VM that
+starts again does not run it again. A new VM does, for example after `ttl` deletes the old one. So write each
+step so that it can run again: check before you install, as the template does. Start from this template. Keep the steps in this order, and give each one its own exit code. The work folder is
+`C:\work\code`. The setup script does not clone the code. It runs before any code host key exists, so a
+clone of a private repository fails, and the machine start fails with it. The agent clones the code in its
+turn, from a git bundle or a public address (`phases/5-prove.md`, section 1).
+
+```powershell
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+# 10: the egress edge's certificate authority is trusted machine-wide. The worker hands the script its path.
+$ca = $env:GIT_SSL_CAINFO
+if ($ca) {
+  try {
+    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($ca)
+    if (-not (Test-Path "Cert:\LocalMachine\Root\$($cert.Thumbprint)")) {
+      Import-Certificate -FilePath $ca -CertStoreLocation Cert:\LocalMachine\Root | Out-Null
+    }
+  } catch { Write-Output "trusting the edge authority failed: $_"; exit 10 }
+}
+
+# 11: the work folder, for the service account and the administrators only.
+try { New-Item -ItemType Directory -Force -Path C:\work | Out-Null } catch { exit 11 }
+icacls C:\work /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' | Out-Null
+if ($LASTEXITCODE -ne 0) { exit 11 }
+
+# 12: Git for Windows. Set the version the team uses.
+$git = 'C:\Program Files\Git\cmd\git.exe'
+if (-not (Test-Path $git)) {
+  $version = '<version, such as 2.47.1>'
+  $installer = 'C:\work\git-setup.exe'
+  try {
+    Invoke-WebRequest -UseBasicParsing -OutFile $installer `
+      -Uri "https://github.com/git-for-windows/git/releases/download/v$version.windows.1/Git-$version-64-bit.exe"
+  } catch { exit 12 }
+  $run = Start-Process -FilePath $installer -ArgumentList '/VERYSILENT', '/NORESTART', '/NOCANCEL', '/SP-' -Wait -PassThru
+  if ($run.ExitCode -ne 0) { exit 12 }
+}
+# For the rest of this script only. The agent does not get this PATH.
+$env:Path = "C:\Program Files\Git\cmd;$env:Path"
+
+# 13: git trusts the Windows certificate store, for every process on the machine.
+& $git config --system http.sslBackend schannel
+if ($LASTEXITCODE -ne 0) { exit 13 }
+
+# 14 and on: the team's toolchain that fits in the time limit, one exit code per step.
+```
+
+Why each step is there:
+
+- `$ErrorActionPreference = 'Stop'` stops on a failing PowerShell command, but not on a failing program such as
+  `icacls` or `git`. So each program call is followed by a `$LASTEXITCODE` check that exits non-zero.
+- The worker already imports the edge's authority into `Cert:\LocalMachine\Root` before the script runs, and
+  logs a failure without stopping. Step 10 checks it, and imports it when it is missing. The worker sets each
+  certificate variable a harness reads, `GIT_SSL_CAINFO` among them, to the authority's file.
+- PowerShell 5.1 does not always offer TLS 1.2, so a download can fail before it reaches the edge.
+- The Windows image has no git.
+- The agent does not find git on its PATH. Its PATH is the worker's, fixed when the worker started, before
+  the setup script ran. The installer's change to the machine PATH and the script's `$env:Path` do not
+  reach it. So the agent calls git by its full path, `C:\Program Files\Git\cmd\git.exe`. Write this in the
+  agent's instructions or in the codebase skill.
+- Git for Windows reads its own certificate bundle, not the Windows store. The worker sets `GIT_SSL_CAINFO` for
+  the setup script and the harness only, so git run any other way fails on the edge's certificate. The
+  `schannel` setting makes every git on the machine read the Windows store.
+- The SIDs `S-1-5-18` (the service account, LocalSystem) and `S-1-5-32-544` (the administrators) work on every
+  language of Windows, where the account names do not. On Windows the agent runs as the worker's account.
+- The setup script has 10 minutes, and the limit is fixed for now. A toolchain such as Visual Studio Build
+  Tools can take 10 to 20 minutes to install. Leave such an install to the agent's first turn: a Windows
+  machine is parked when idle and keeps its disk, so it stays installed. The agent waits for the install in
+  the turn: a park kills an install that is still running. A process the setup script leaves running is
+  killed the same way. For machines that start with it
+  installed, use the team's own image ("Windows in three stages", stage 2).
+- The output is kept as it is. Never print a token.
+
+### C. Where the machines run, when the code needs private services
+
+Choose here when development needs a database, internal APIs or a package feed inside the team's network
+or cloud. List what the code needs, host by host, before you choose.
+
+| | Hosted | A compute provider in their cloud | Their own machine | The whole platform in their cloud |
+|---|---|---|---|---|
+| Benefit | The simplest start. Nothing to run. Keys added at our network edge, machine endpoints and views, machines kept ready, and we keep it running. | Keeps their setup, networks, images and private services inside their own cloud, under their own account and controls. | Their own machine or network, as it is. | Nothing leaves their cloud. |
+| What reaches what | Our machines reach their services over the internet, through the network edge | Their Launcher asks our platform for orders over HTTPS. Their machines connect out to our platform. Nothing connects in. | The worker on their machine connects out to our platform | All inside their cloud |
+| Where keys live | Secrets, added at our network edge | On their machines, set by their own boot step. No network edge of ours stands in front of their machines yet | On their machine | In their cloud |
+| Where files rest | Our object store (S3) | Not stated yet | Not stated yet | Their cloud |
+| Setup | None | Make a compute provider record, deploy the Launcher template to their Azure subscription, name the record in `provisionSpec.computeProviderId` | Enroll the machine (`orchestra worker enroll`) | An installation of the platform's Helm chart |
+| Status | Released | Released on Azure. Not released yet: AWS | Released | Not released yet |
+
+Pick hosted when the private services can be reached over the internet with a key.
+Pick a compute provider when the services must stay inside their cloud, and they use Azure.
+Pick their own machine when the code needs one machine they already run, such as a Mac.
+
+Tell the developer the benefit of each choice first. The limits are for troubleshooting. Do not lead with
+them when you present the choice.
+
+Cannot do:
+
+- Hosted: reach a service that is not on the internet.
+- A compute provider: run on AWS or Google Cloud; run on arm64; keep `/home` on a Kata pod target; add
+  keys at our network edge.
+
+Tokens on a compute provider's machines:
+
+- The team manages every credential on their own machines. The platform delivers none there.
+- The model sign-in goes in the worker service's own environment, by harness:
+  - `claude` with a Claude subscription token: `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`.
+  - `claude` with an Anthropic API key or an Orchestra gateway key: `ANTHROPIC_API_KEY`. This value
+    replaces the placeholder that our image sets. With a gateway key, keep the agent's model gateway on:
+    the platform sets the gateway address.
+  - `codex`: `ORCHESTRA_WORKER_OPENAI_API_KEY`, or `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`.
+  - On Windows, the worker service is `SfdkWorker`, and its environment is the service's `Environment`
+    registry value.
+- Other tokens, such as for git, a package feed or an Azure DevOps personal access token: the team's own
+  boot step sets them. For example, the step reads their Key Vault with a managed identity on the VM.
+- The worker reads its environment when its service starts. So the boot step runs before the worker
+  starts, or restarts the worker service after it sets the values. On our Windows image, the startup task
+  `orchestra-azure-userdata` starts `SfdkWorker` at each boot.
+- Do not put a token in the environment's `env` (`provisionSpec.env`). The platform stores it, an
+  environment read returns it, and it travels in plain text in the VM's startup data.
+- The Launcher attaches no managed identity to the VMs it creates. The team's automation finds the VMs by
+  two tags: `orchestra-launcher` holds the compute provider record's id, and `orchestra-machine` holds
+  the machine's id. Not released yet: a managed identity attached when the Launcher creates a VM.
+- Never bake a credential into an image: that is not supported.
+- Not released yet: our network edge for machines in the team's own network, which adds keys from
+  Secrets as it does for hosted machines.
+
+The Launcher's VM targets use the `Dsv5` size family by default. A subscription with no `Dsv5` capacity
+sets `vmSizeFamily: Dsv6` on each VM target in the Launcher's settings.
+- Their own machine: hold network rules; add keys at the edge; start a machine on demand.
+
+When no choice fits, write down what is missing and stop here. Report it to the developer, and go back to
+the orchestra-fdk skill. They can still see a first fix on the todo sample, or on the parts of the code
+that need no private service.
 
 ## 6. Write and check
 
@@ -421,38 +678,89 @@ Write down what is missing and stop here. Report it to the developer, and go bac
 2. In `<factory>`, run `npm run typecheck`, then `npx orchestra fdk synth`. The starter is one program, at the folder's
    root.
 3. Read `<factory>/fdk.out/plan.json`. Every environment has your setup script, ports and settings, and
-   the model rule from step 6 of the orchestra-fdk skill: the `model-gateway` rule,
-   or a Secret's rule on the provider's host. On a new factory, no environment has a Bitbucket or Jira rule
-   yet: those come with the tokens, in step 12 of the orchestra-fdk skill. On an existing factory, with its
-   inputs loaded, the rules it has now stay as they are.
+   the model rule of the orchestra-fdk skill's phase 2: the `model-gateway` rule, or a Secret's rule on the
+   provider's host. On a new factory, no environment has a code host or tracker rule yet: phase 3 adds them
+   after the first run. On an existing factory, with its token file loaded, the rules it has now stay as
+   they are.
 4. Write `ENVIRONMENT.md` in `<factory>`: what you found and where, the mode you proved in and its result
    for each success criterion, the commands, every outbound attempt the proof logged, and what is still
    unknown.
 
 **Check:** the typecheck and the synth pass, and the plan is as in item 3. Go back to the orchestra-fdk
-step that sent you for the apply.
+skill's phase 4 for the apply.
 
 ## 7. The cloud
 
 The cloud is the fallback when no local mode can run. It is also the confirmation after the local proof:
-the Manager Agent's "Set up" item, which step 10 of the orchestra-fdk skill starts. It proves what only the
-cloud can: the micro VM, Docker, the network rules and the tokens. The Engineer Agents' machines cannot clone from
-Bitbucket, so the Set up item also proves the tests run from a git bundle.
+the Set up item, which phase 5 of the orchestra-fdk skill starts. It proves what only the cloud can: the
+micro VM, Docker, the network edge and the machine endpoints. The Engineer Agents start each item from a git
+bundle, so Set up also proves the tests run from one.
 
 It is slower. Each try is an apply plus a machine start, and access problems show one at a time.
 
-To prove in the cloud, write the environment as in sections 5 and 6, apply it, and run Set up with the git
-bundle. Keep the safety rule:
-
-1. For the proof, set the environment's default action to `deny`. Allow only the package registries and
-   image registries the install uses, and keep the `model-gateway` rule. Calls to the Orchestra platform
-   skip these rules.
-2. Use only local settings in the Set up item's instructions.
-3. Ask the Manager Agent to report every refused host, and to note any production host it sees and
-   continue.
-
-When a step fails, fix it here, prove the fix locally if a local mode runs, apply again, and assign the
-item again.
+To prove in the cloud, write the environment as in sections 5 and 6, apply it, and run Set up. Egress stays
+open. Keep the safety rule this way:
+
+1. Use only local settings in the Set up item's description.
+2. Ask the Manager Agent to note any production host it sees in a setting or a log, and to continue.
+
+When a step fails, fix it here, prove the fix locally if a local mode runs, apply again, and assign Set up
+again. `troubleshooting.md` names each failure.
+
+### The model in the cloud: subscription, model gateway, or own key via the vault
+
+The cloud agents reach a model in one of three ways. Ask the developer which one, and walk them through
+its steps once. They copy every value themselves; you never read, print or copy it.
+
+1. **Subscription: their own Claude or Codex sign-in.** Follow the sign-in steps below.
+2. **Model gateway: Orchestra provides the key.** One endpoint reaches OpenAI, Anthropic and open-source
+   models, on the organization's credits. They can also bring their own provider key to the gateway, with
+   `orchestra fdk init --model-key anthropic` or `openai`. The gateway also routes models:
+   `orchestra model-configs` sets which providers serve a model and in what order, so a call falls back to
+   the next one when a provider is down, and `orchestra model-aliases` gives a model a name of their own, such as `default`.
+3. **Own API key via the vault.** Their Anthropic or OpenAI API key is a platform Secret, added at the
+   network edge on calls straight to `api.anthropic.com` or `api.openai.com`, with no gateway in between
+   and with the agent's gateway setting off. Nothing to sync, because an API key does not renew. When they
+   have an API key, recommend this over a subscription: no file to copy and no shared `/home`.
+   `references/authoring.md` § How the agents reach a model shows the declaration.
+
+The sign-in steps. The developer makes the sign-in in a real terminal on their computer; run from an
+agent's shell, its browser step hangs.
+
+- **Claude: a long-lived token in a Secret, the recommended way.** `claude setup-token` prints an
+  `sk-ant-oat…` token made for servers. It lasts about a year, and nothing on a machine renews or revokes
+  it, so it needs no shared `/home`. Save it to a file only the developer can read, never through a chat:
+  copy it, then `umask 077 && pbpaste | tr -d '\n' > <file> && pbcopy </dev/null`. At apply, the shell
+  exports it from that file into the variable a `Secret` reads. An egress rule allows `api.anthropic.com`
+  and adds `Authorization: Bearer ${secret}`, removing `x-api-key`. The environment's `env` holds only
+  `CLAUDE_CODE_OAUTH_TOKEN=software-factory-egress-placeholder` and an empty `ANTHROPIC_API_KEY`, and the
+  agent's gateway setting is off. Never put the token itself in `env`. The Claude sign-in recipe in
+  `references/authoring.md` shows the declaration. Copying the renewing credentials file is the fallback,
+  and follows the ChatGPT sign-in steps below.
+- **Codex: a personal access token, where the workspace allows one.** A ChatGPT Business or Enterprise
+  member creates it at chatgpt.com/admin/access-tokens, once the workspace owner allows access tokens,
+  and chooses how long it lasts, such as 7 to 90 days. Codex never renews it, so it needs no shared
+  `/home`; the developer supplies a new one before it expires. It begins `at-` and goes in
+  `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`, which outranks a ChatGPT sign-in or an API key beside
+  it. On their own computer, `codex login --with-access-token` reads the same token from standard input.
+- **Codex otherwise: a separate ChatGPT sign-in on a shared `/home`.** The other long-lived choice is an
+  OpenAI API key, billed by use rather than by the subscription (option 3).
+  1. **Make a separate sign-in, never a copy of the local one:** `mkdir -p <dir> && CODEX_HOME=<dir> codex
+     login` (`--device-auth` only with no browser). Its tokens in `<dir>/auth.json` go in the
+     `ORCHESTRA_WORKER_CODEX_` variables, or a setup step writes the file.
+  2. **Give the environment a durable `/home` volume,** shared by every machine that uses the sign-in, so
+     one file renews for all of them. Each renewal replaces the refresh token, so separate copies sign
+     each other out; two machines that renew in the same second can too, and then need a new sign-in.
+     Remove the variables after the first machine starts.
+  3. **Never sign in again in the default folder after the copy.** A new `codex login` in `~/.codex`
+     revokes the cloud copy, and every machine answers "refresh token was revoked". If it happened, make
+     a new separate sign-in.
+- **Keep a Codex sign-in off an agent that uses the model gateway.** With a ChatGPT sign-in or a personal
+  access token, Codex compresses its requests, and the gateway refuses them with `model_not_found`, a
+  known issue. Give such an agent the subscription directly, with its gateway setting off, or keep the
+  homes apart.
+
+The sign-in values are plain text: the environment's settings are stored unencrypted and shown on every read.
 
 ## What the platform can do
 
@@ -460,8 +768,9 @@ Use the orchestra skill to build an answer for a case the paths do not cover. Ne
 yet" lines. The sections this work needs:
 
 - Section 4: environments, machines, sizes, images, setup scripts, disks, Windows and full VMs.
-- Section 5: network rules, their live effect on running machines, and commissioning.
+- Section 5: network rules, and their live effect on running machines.
 - Section 6: secrets, and where their values come from.
 - Section 7: the model gateway rule every environment needs.
-- Section 17: connections, the later option for the code host and the tracker.
+- Section 17: connections. The files under `references/integrations/` say how to give access to each
+  service.
 - Section 18: the team's own machines, the local environment, and private networks.