宿主环境

---
name: host-env
description: Holds the procedure in which the lead agent of the `update env` command checks this host, gets the local models and programs of harness settings and actually runs them, and, when they do not match, proposes a harness settings revision to the human. Read when receiving `update env`
---

# host env

`update env` is a command outside the loop. Harness settings are edited only with the revisions that a human accepted.

## procedure

1. Check the host with `ogw env check`: OS, CPU, memory, free disk, git, Node, uv, Python, Docker and `docker buildx`, GitHub CLI login and its scopes, engine, the programs (`tools.chromium`, `tools.gdtoolkit`, `tools.ffmpeg` included) and image (`tools.postgresql`) of harness settings `tools`, per game in `games/` the build toolchain of its `buildPlatforms` (`buildTools` of `engine.json` of that game's core version), the installation and login of the agent CLIs that harness settings `agents` uses, for each method of harness settings `resourceGeneration` that has `provider` the installation and login of that provider CLI (`codex`, `grok`) and the billing of the calls of that method, whether one short prompt, run per agent CLI in a newly made empty folder with the same flags as `ogw agent`, finishes, whether the devices of harness settings `testDevices` are in `adb devices`, whether UDP from an android device reaches the LAN address of the host (it checks that the host receives a datagram that `adb shell` sends to a UDP port the host opened), whether the hf pin `secret` of harness settings `resourceGeneration` is in the host secret store, and, when the agent CLI of play or judge in harness settings `agents` is Claude Code, whether the harness secret `claude-code-oauth-token` is in the host secret store and, when it is, whether the two checks that `ogw secret set` does before it puts in that secret pass (whether the value can be an HTTP `Authorization: Bearer` header value, and whether a short prompt run on Claude Code with that value inside the agent sandbox of play or judge passes; when the first check does not pass, the second check is not done)
   - When a program among `buildTools` whose `hosts` has this host and that has no `downloads` is not on this host or has a different version, tell the human the program and version to install
   - provider login and billing: `codex` is logged in when `codex login status` ends with code 0. The billing is `subscription` (the usage of the ChatGPT subscription) when the login kind that this command prints after `Logged in using` is `ChatGPT`, and `per-call` (each call billed to that key) when it is `an API key`. `grok` is logged in when `auth.json` exists in `GROK_HOME`, or in `~/.grok` when `GROK_HOME` is not set. The `grok` CLI writes and refreshes that file, and sprite-gen sends its token to the xAI API itself; the billing is then `subscription` (the usage of the Grok subscription). Without that file, sprite-gen uses `XAI_API_KEY`, and the billing is `per-call` (each call billed to that key) when it is set. The value of `XAI_API_KEY` is not written in the result. In any other case the billing is `unknown`
2. With `ogw env install-engines --background`, get the engines and the programs among `buildTools` of `engine.json` whose `hosts` has this host and that have `downloads`. Start it together with step 3. The versions to get are all those written in the `engine.json` of the core release that the core version of game settings points to, per game in `games/`, and in `open-game-works-core-impl/client/<engine>/engine.json`. Fetched files are checked against the SHA-256 written in `engine.json`
3. With `ogw generation install --background`, get harness settings `tools` and the `pins` of `resourceGeneration`. When the revision or SHA-256 of a fetched file differs from the pinned information, that method is left as failed. An `external-service` method without `provider` has nothing to get; check that its `secret` is in the host secret store, and when it is not, tell the human to put in a non-empty value with `ogw secret set --harness <secret name>`. A method whose git pin has no `revision` is not fetched and is left as failed. A pip pin is installed in the isolated environment of the method. The git pin repository of a `local-model` method is not installed, so its `pyproject.toml` `dependencies` must be in the pip pin (`pin:<method>` of step 6). An hf pin with `secret` is fetched with the Hugging Face access token of that harness secret, and a method whose secret is not in the host secret store is not fetched and is left as failed. For an hf pin with `sha256`, that `sha256` is matched against the SHA-256 of the LFS file that Hugging Face publishes before the LFS files are fetched, and each fetched LFS file is matched against the published SHA-256. An hf pin without `sha256` is fetched without checking the fetched files. When a method installation fails, among the LFS files that hf pins fetched, only the files whose SHA-256 equals the SHA-256 that Hugging Face published are kept, and the method is treated as not fetched. When a method is fetched again (when `pins` changed or the previous installation failed) and the previous installation has an hf pin with the same `source` and `revision`, the LFS files that pin fetched and left whose SHA-256 equals the SHA-256 that Hugging Face published are used without being fetched again. Other files and pins are fetched anew. To fetch only one method again, use `ogw generation install <method> --background`. This call does not get `tools`, and changes only the item of that method in the result file
4. When the job of step 3 ends, run the standard test task of each method stage by stage with `ogw generation measure [--allow <method,...>] --background`. `--allow` is the `external-service` methods whose calls the human allowed. To measure only a few methods again, use `ogw generation measure <method>... [--allow <method,...>] --background`. This call changes only the items of those methods in the result file
   - The stages (resolution, length) and the test inputs are fixed in the tool per method. Stages run from the lowest
   - Per stage, the result (`ok`, `failed`, `timeout`) and the duration taken are written. When a stage exceeds the `safetyTimeoutMs` of that method, it is cut off and is `timeout`
   - When `failed` or `timeout` comes out, the higher stages are not run
   - The tool gives the peak memory and the result file path per stage, and for a `failed` or `timeout` stage also the last 20 lines of stderr of the stopped call (`error`). These three are not put in harness settings
   - The tests of `local-model` methods and `blender` methods run in a sandbox that blocks the network and confines writes to the folder of that method. The sandbox runs only on macOS and Linux; on any other OS that test fails
   - Among `procedural` methods, the methods other than `blender` and `rig-2d` have no standard test task. One `ok` stage without resolution and length is written
   - For `rig-2d`, one `ok` stage is written when `flux2-klein` has an `ok` stage (the result measured in this measurement; when this measurement did not measure it, the result in the result file; when it could not be measured, harness settings `measured`) and `ogw resource rig-split`, `rig-check`, `rig-mesh` pass the fixtures fixed in the tool, and otherwise one `failed` stage is written
   - When the sandbox blocked an access, it is written in the result
   - For an `external-service` method, first tell the human the cost of one test call, and pass only the allowed methods with `--allow`. A method not in `--allow` is not called, and that fact is written in the result. The result holds the duration taken and the cost; memory is not measured
   - An `external-service` method without `provider` has no standard test call, so it is not called, and that fact is written in the result
   - For a method with `provider`, tell the human the billing of its calls from step 1 before asking: `subscription` uses the usage of that subscription, `per-call` bills each call to that key, and for `unknown` the human has to check the login. Call only the allowed methods. The cost in the result is 0 for every billing
   - `catalog` methods have no standard test task. When the files fetched in step 3 are the same as the pinned information, one `ok` stage without resolution and length is written
5. When the jobs of steps 2 and 4 end, measure the number of instances that can be started concurrently with `ogw instance measure --background`
   - The targets are the benchmark game of the highest release, among the releases of harness settings `coreReleaseRepository`, that has `benchmark-<engine>.zip`, and the games in `games/` that have `client/dev/bot/scenario.json`. When there is no target, nothing is measured
   - Per target, measure while varying the number of instances N. To measure N, start N instances that render the screen together, run that scenario in each instance, then stop them all. The value of the target is the largest N at which every instance keeps the `fps` condition of the `## performance` judgement of [performance of `game-loop`](../game-loop/performance.md) (the `targetFps` of the benchmark game is the `targetFps` default of the game settings schema) and no process ended abnormally. Fps is taken to fall as N grows. `maxConcurrentInstances` does not limit this measurement. When an instance fails to start while instances are being added, that N counts as not kept, and the reason is written in the result. When, while measuring 1 instance, that instance fails to start or the standard test task run together with it fails, the measurement fails and writes no result
   - The first N measured is harness settings `maxConcurrentInstances` of this host, or, when there is none, half the CPU count of this host (at least 1). The upper limit is 8. Measure the next N until the largest N that kept the condition and the smallest N that did not differ by 1: when there is no N that failed yet, the value + 1 when the N that kept it is `maxConcurrentInstances`, otherwise double the N that kept it (up to the upper limit); when there is no N that kept it yet, half the N that failed; otherwise the middle of the two N (rounded down)
   - It measures while running together one standard test task: the one with the largest peak memory among the `local-model` method stages that are `ok` in step 4
6. With `ogw env propose`, get the revisions and notices that compare the results of steps 1 to 5 with harness settings. The tool gives, per revision, an id, the harness settings path, the current value, the new value and the reason, and gives only the revisions and notices below. It gives no revision or notice for a step without a result.
   - revision `measured:<method>`: per method, replaces `measured.<method>` with the result of step 4
   - revision `maxConcurrentInstances`: the smallest of the target values measured in step 5. Not given when that value is less than 2
   - revision `playInstances`: when the smallest of the target values measured in step 5 is 2 or more and less than harness settings `playInstances`, changes `playInstances` to that value
   - revision `tools.postgresql`: when step 3 could not get the image, changes it to the highest `<major>.<minor>` tag of Docker Official Image `postgres` whose major is the same as that of `tag`, and its digest
   - revision `pin:<method>`: the target git pins are the git pins without `revision` and every git pin of `local-model` methods. For a git pin without `revision`, the HEAD commit of the default branch of its repository is written as `revision`. The `[project] dependencies` of `pyproject` (`pyproject.toml` when that pin has none) at that commit of a target git pin, and the pip pin entries of the projects that those dependencies do not name (by PEP 503 normalized name), are resolved with `uv pip compile` per macos-arm64 (macOS 14.0 or later), linux-x64 and windows-x64 with the CPython version of the method's isolated environment, and every package down to dependencies of dependencies is pinned as `<name>==<version>`. The results of the three platforms are merged into one pip pin: an entry that is the same on all three platforms stays without a marker, and an entry that differs gets the `sys_platform` marker of the platforms that receive it. This pip pin replaces the first pip pin, and the other pip pins are dropped. When there is no pip pin, it is added at the end. A PEP 440 local version label (`torch==2.7.1+cu128`) is not on PyPI, so it is resolved with the label removed. A project not on PyPI is not put in, and is written in the reason. Among the direct references (`<name> @ <URL>`) of the dependencies, a `git+` URL whose repository is `https://` or `ssh://` is pinned to the commit that the ref of that URL (HEAD when there is none) points to and is put in as `<name> @ git+<repository>@<commit>`; any other URL is not put in, and is written in the reason. For a platform that does not resolve, the packages of that method are not fetched, and that platform and the uv error are written in the reason. When none of the three platforms resolves, it gives no revision, gives the uv error and fails. When `pins` does not change, it is not given
   - revision `sha256:<method>`: for each hf pin without `sha256` among the hf pins of the methods fetched in step 3, writes the `sha256` calculated from the fetched files. Even after this revision is applied, step 3 does not fetch that method again
   - revision `tools.gdtoolkit`: when there is no `tools.gdtoolkit` or step 3 could not get it, adds the pinned information of the `any` wheel of the highest version of PyPI `gdtoolkit` whose major version is the same as the Godot major version of `open-game-works-core-impl/client/godot/engine.json`, and of every wheel that wheel depends on (dependencies of dependencies included). Dependency wheels are chosen per macos-arm64, linux-x64 and windows-x64, and `python` is the highest CPython `3.<minor>` for which all three platforms have the dependency wheels
   - revision `tools.ffmpeg`: when there is no `tools.ffmpeg` or step 3 could not get it, adds pinned information with the URLs of the assets `ffmpeg-darwin-arm64` (macos-arm64), `ffmpeg-linux-x64` (linux-x64), `ffmpeg-win32-x64` (windows-x64) in tag `b6.1.1` of GitHub release `eugeneware/ffmpeg-static`, and the SHA-256 digests that GitHub gives for those assets. These builds contain the `libvorbis` encoder
   - notice `no-benchmark`: there is no target measured in step 5. `update env` has to run again after `create client core`
   - notice `no-loop`: the smallest of the target values measured in step 5 is less than 2. This host cannot run the loop
   - notice `no-method`: the list of resource types that the methods of harness settings `resourceGeneration` cannot make
   - notice `docker`: Docker or `docker buildx` is missing, or the GitHub CLI login has no `write:packages` scope. It has to be installed, or logged in with `gh auth refresh --scopes write:packages`
   - notice `udp`: the list of android devices that UDP does not reach. The check `device performance` of a realtime game becomes `unknown`, so the devices have to be on the same LAN as the host
   - notice `agent-cli`: the agent CLIs that did not finish in an empty folder, and their error output
   - notice `agent-login-token`: the agent CLI of play or judge is Claude Code, and the harness secret `claude-code-oauth-token` is not in the host secret store (`missing`), or the value cannot be an HTTP `Authorization: Bearer` header value or Claude Code failed authentication in the check of step 1 (`invalid`), or the check failed for another reason (`unverified`; the error is given with it). For `missing` and `invalid`, a human has to make a long-lived token with `claude setup-token` and put it in as one line with `ogw secret set --harness claude-code-oauth-token`. For `unverified`, a human has to check that error. Without this secret, `ogw loop start` and `ogw build start` do not start
   - notice `pin-secret`: the hf pin `secret` values that are not in the host secret store, and the repository of each pin. A human has to accept the license on the page of that repository on Hugging Face and put in the access token of that account with `ogw secret set --harness <secret name>`. When `update env` runs again after that, step 3 fetches that method, and step 6 gives the `sha256:<method>` revision
   - notice `provider-cli`: the provider CLIs that are not installed or not logged in, or whose billing in step 1 is `per-call`, or `unknown` while logged in, and the methods that use them. For a CLI that is not installed or not logged in, a human has to install it and log in. For `per-call`, it names the login that makes the calls use the subscription instead (`codex login` with ChatGPT, `grok login`). For `unknown`, a human has to check how that login bills the calls
7. Decide the revisions that the tool does not give
   - a failed method: a revision that removes it, or a revision that fixes `pins`
   - when `tools.chromium` is missing or could not be fetched: a revision that adds the pinned information of Chrome for Testing `chrome-headless-shell` for the OS of this host
   - a method outside `catalog` whose `license` is missing or `unknown`: a revision that fills `license` by `## resource rights` of [`resource`](../resource/SKILL.md). For a method with pins and without `provider`, it holds the model card license of its pins. For a method with `provider`, it is the license reference of the output terms of that provider, not the license of the code that its pins fetch
   - the CLI of notice `agent-cli`: a revision that changes the `agents` items of the roles that use that CLI to another CLI
8. Show the human the measurement results, the revisions and notices of step 6, and the revisions of step 7. Apply the revisions of step 6 that the human accepted with `ogw env propose --apply <id,...>` and those of step 7 with `ogw settings set harness`, then commit. `--apply` writes, per revision, only the parts where the current value and the new value differ, so revisions with the same path are also applied together. When revisions whose differing parts overlap are given together, it writes nothing and fails. In that case apply them one at a time, and run `ogw env propose` again after each one
9. Delete the test result files after the human has seen them

- Accesses that the sandbox blocked and files that differ from the pinned information are told to the human before the measurement