Integrate Sandbox deployment and supporting tools

.github/workflows/ci.yml

@@ -31,6 +31,35 @@ jobs:
       - name: Public tree audit
         run: bash scripts/audit_public_tree.sh
 
+  documentation-history:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Audit documents in every new commit
+        env:
+          DOCUMENTATION_BASE: ${{ github.event.pull_request.base.sha }}
+        run: bash scripts/audit_public_tree.sh --history-base "$DOCUMENTATION_BASE"
+
+  sandbox-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install optional runtime and practice
+        run: python -m pip install -e '.[dev,sandbox]' -e practices/h_cluster
+      - name: SDK contracts without allocation
+        run: python scripts/sandbox_sdk_contract.py
+      - name: Optional lifecycle and practice tests
+        run: python -m pytest tests/harborrl/test_sandbox_cleanup.py practices/h_cluster/tests
+
   package:
     runs-on: ubuntu-latest
     needs: cpu

.gitignore

@@ -32,7 +32,20 @@ harbor_datasets/
 .tools/
 .worktrees/
 benchmarks/harbor/0.5-mvp/
-docs/
+docs/*
+!docs/agents/
+docs/agents/*
+!docs/agents/environment-check.md
+!docs/configuration-wizard.md
+!docs/deployment.md
+!docs/sandbox-rollout.md
+!docs/train-inference-consistency.md
+!docs/web-console.md
+practices/**/VALIDATION.md
+practices/**/HISTORICAL_VALIDATION.md
+integration-report-*.md
+integration-roadmap-*.md
+*.bundle
 local/
 configs/site/
 examples/**/private*

CONTRIBUTING.md

@@ -13,6 +13,25 @@ HarborRL accepts changes through pull requests from a public branch.
 6. Submit a reviewable commit series and describe external versions, task
    provenance, and any acceptance evidence.
 
+## Public documentation
+
+Commit documentation that helps users install, configure, run or troubleshoot
+HarborRL. Keep development plans, integration reports, experiment logs and
+machine-specific validation records outside the repository. Summarize current
+support and limitations in the relevant user guide without development history.
+
+The public-document allowlist is maintained in `scripts/audit_public_tree.sh`.
+Update it deliberately when adding a user guide. Check both the final tree and
+every new commit before opening a pull request:
+
+```bash
+bash scripts/audit_public_tree.sh --history-base origin/main
+```
+
+Deleting a private document in a later commit does not remove it from history.
+Clean unpublished commits before pushing; do not merge a development branch
+whose history contains private documents into a public branch.
+
 Configuration and task fixtures must use generic placeholders. Absolute personal
 paths, internal DNS names, private registry references, and unexplained large
 files will fail review.

NOTICE.md

@@ -2,6 +2,10 @@
 
 HarborRL is MIT-licensed by Princeton-AI.
 
+The local web console bundles Lucide 1.61.0 (ISC license). Its unmodified browser
+distribution and license are in `harborrl/webui/static/lucide.min.js` and
+`harborrl/webui/static/lucide-LICENSE.txt`. No CDN connection is required.
+
 The public package does not vendor Slime, Megatron-LM, SGLang, Harbor, Claude
 Code, or model weights. Operators are responsible for reviewing the licenses of
 the exact external versions they pin and for complying with model and dataset

README.md

@@ -2,9 +2,9 @@
   <img src="assets/HarborRL-title.jpg" alt="HarborRL" width=800>
 </p>
 
-<!-- <p align="center">
+<p align="center">
   <h1>HarborRL</h1>
-</p> -->
+</p>
 
 <p align="center">
   <strong>A lightweight agentic reinforcement learning framework for everyone</strong>
@@ -25,6 +25,8 @@
 
 ## News
 
+- **2026-10-26** Added an [offline configuration wizard](docs/configuration-wizard.md) and a [local Web console](docs/web-console.md) for configuration, validation, dry-runs, training launch, and logs.
+- **2026-10-26** Added [controller/GPU deployment configuration](docs/deployment.md), optional [OpenSandbox execution](docs/sandbox-rollout.md), and opt-in [train/inference consistency checks](docs/train-inference-consistency.md).
 - **10/2026** 📣📣📣 HarborRL released
 
 ## About
@@ -40,6 +42,14 @@ HarborRL supports flexible combinations of **Models × Algorithms × Tasks × Ha
 
 ## AI-assisted Configure
 
+For the offline options catalog, interactive configuration, and answer-file setup,
+see the [configuration CLI guide](docs/configuration-wizard.md).
+Start with `harborrl options` or `harborrl init --help`.
+
+Run `harborrl web` to open the local browser console for configuration, validation,
+dry-runs, training launch, and logs. See the [web console guide](docs/web-console.md)
+for remote-controller access and lifecycle details.
+
 If you want an AI agent to help deploy this repository and verify training,
 ask it to first read and strictly follow
 [docs/agents/environment-check.md](docs/agents/environment-check.md).
@@ -78,6 +88,12 @@ Confirm the result yourself against this checklist:
 
 ## Quick Start
 
+The default CPU install does not need a Sandbox SDK or cluster account.
+For controller placement, see [deployment](docs/deployment.md). For optional
+standard OpenSandbox execution, see [Sandbox rollout](docs/sandbox-rollout.md).
+The independently installed [H-cluster practice](practices/h_cluster/README.md)
+contains Brainbox-specific deployment and restricted-network relay examples.
+
 ### Install
 
 Use Python 3.10 or newer. Runtime dependencies, development dependencies, and the `harborrl` command are locked by [pyproject.toml](pyproject.toml) and [uv.lock](uv.lock). The CPU development install does not require CUDA, Docker, model weights, Slime, Megatron-LM, or SGLang.
@@ -128,7 +144,7 @@ The command style is a shorthand over `config.yaml` in the working directory (or
 
 ## Task Configuration
 
-Training is configured with one YAML file that has a fixed section and field set. Relative paths resolve against the YAML file, and repeated `--set section.field=value` overrides are parsed as YAML values and validated again. Start site-specific configurations from [examples/native/train_qwen_native.yaml](examples/native/train_qwen_native.yaml).
+Training is configured with one YAML file that has a fixed section and field set. Relative paths resolve against the YAML file, and repeated `--set section.field=value` overrides are parsed as YAML values and validated again. Start site-specific configurations from [examples/native/train_qwen_native.yaml](examples/native/train_qwen_native.yaml). Optional [train/inference consistency checks](docs/train-inference-consistency.md) compare frozen rollout scores with the pre-update trainer and probe synchronized inference engines.
 
 The configuration has three broad parts: `execution` is fixed to `harbor_job`; `harbor`, `gateway`, and `deployment` describe rollout workers, service endpoints, and GPU topology; `tasks`, `harness`, `model`, `training`, `sampling`, and `output` describe the experiment and its outputs.
 

README_zh.md

@@ -25,6 +25,8 @@
 
 ## News
 
+- **2026-10-26** 新增[离线配置向导](docs/configuration-wizard.md)和[本地 Web 控制台](docs/web-console.md)，支持配置、校验、dry-run、训练启动和日志查看。
+- **2026-10-26** 新增 [controller/GPU 部署配置](docs/deployment.md)、可选的 [OpenSandbox 执行能力](docs/sandbox-rollout.md)，以及按需启用的[训练与推理一致性检查](docs/train-inference-consistency.md)。
 - **10/2026** 📣📣📣 HarborRL released
 
 ## 项目介绍
@@ -43,6 +45,11 @@ HarborRL 支持 **Models × Algorithms × Tasks × Harnesses (MATH)** 的灵活
 如果你希望让 AI agent 辅助完成本 repo 的部署和训练验证，请让它先阅读并严格遵循
 [docs/agents/environment-check.md](docs/agents/environment-check.md)。
 
+离线选项目录、交互式配置和 answer-file 配置方式见[配置 CLI 指南](docs/configuration-wizard.md)。
+可以从 `harborrl options` 或 `harborrl init --help` 开始。
+运行 `harborrl web` 可打开本地浏览器控制台，完成配置、校验、dry-run、训练启动和日志查看；
+远程访问与生命周期说明见 [Web 控制台指南](docs/web-console.md)。
+
 推荐的实际操作流程是把下面这段提示词交给 agent，并把尖括号内容替换成你的机器信息：
 
 ```text
@@ -73,6 +80,10 @@ doctor 和 launch_native --dry-run。
 
 ## 快速开始
 
+默认 CPU 安装不需要 Sandbox SDK 或集群账号。
+controller 与 GPU 的部署方式见[部署指南](docs/deployment.md)，可选的标准 OpenSandbox 执行方式见[Sandbox rollout 指南](docs/sandbox-rollout.md)。
+独立安装的 [H-cluster 实践包](practices/h_cluster/README.md)提供 Brainbox 部署与受限网络中继示例。
+
 ### 安装
 
 使用 Python 3.10 或更新版本。Python 依赖、开发依赖和 `harborrl` 命令由 [pyproject.toml](pyproject.toml) 与 [uv.lock](uv.lock) 锁定。CPU 开发环境不需要 CUDA、Docker、模型权重、Slime、Megatron-LM 或 SGLang。

docs/configuration-wizard.md

@@ -0,0 +1,140 @@
+# Configuration CLI
+
+The configuration tools run with the core package (Python 3.10+ and PyYAML).
+They enumerate implemented capabilities, check configuration offline, and create
+consistent training schema 2 / deployment schema 1 files. They do not install
+software, download tasks or models, connect over SSH, or allocate Sandbox/GPU jobs.
+
+## Browse and validate
+
+```bash
+harborrl options
+harborrl options deployments --json
+harborrl options fields --json
+harborrl validate site/config.yaml --deployment site/deployment.yaml --json
+harborrl validate site/config.yaml --deployment site/deployment.yaml --check-files
+```
+
+Catalog dimensions are `models`, `algorithms`, `tasks` (task providers),
+`harnesses`, `datasets`, `deployments`, `fields`, and `compat`. JSON keeps the
+`catalog_version` and `schema_versions` envelope when selecting a dimension.
+The catalog reflects registered implementations, not roadmap claims. Dataset
+`status` describes support; `available` describes local task files. A wheel does
+not include repository examples, and planned datasets are not ready to train.
+
+Validation defaults to schema, semantics, and cross-file consistency. It does
+not open referenced profiles or tasks until `--check-files` is supplied. Run file
+checks on the controller: its source/interpreter, profile, task catalog and
+Sandbox configuration belong there. Local GPU and runner paths are checked
+locally; SSH target paths are deferred. The shared root may be created by a later
+run and is not required to exist during configuration. Credentials are never read.
+
+Checks are `passed`, `failed`, or `deferred`. The report is `invalid` if a check
+fails, otherwise `valid_with_deferred_checks` while live checks remain. Exit codes
+are 0 for no failed checks, 1 for validation/creation failure, and 2 for CLI usage
+errors. `--json` writes one JSON object to stdout. Schema validators may report
+only their first error. Without `--deployment`, the existing CLI discovery of
+`./deployment.yaml` and embedded fallback is preserved and reported.
+
+GPU memory fit, model loading, live tokenizer fingerprints, package versions,
+connectivity and platform capacity are not established by offline validation.
+Sandbox image bindings are checked locally; trusted site adapters and credentials
+are checked later by runner preflight. Sandbox installation/profile timing
+compatibility is additionally checked by the existing training dry-run.
+
+## Prepare inputs
+
+1. Obtain Harbor-format tasks and run `harborrl hub inspect --tasks-dir /path/tasks
+   --dataset my-tasks --revision pinned-revision --run-dir /path/inspection`.
+   The resulting JSONL is an inspection report, not a training catalog. Build a
+   JSON list (or JSONL records with a `.jsonl` suffix) containing exactly `id`,
+   `revision`, `path`, `task_digest`, and `reward_profile` for each selected task.
+   Copy `path` and `task_digest` from a `NEEDS_PROBE` inspection record, assign a
+   unique stable `id`, retain the pinned revision, and explicitly set the verifier's
+   reward contract (for example `reward_profile: {key: reward}`). See
+   [the catalog example](../examples/native/catalog.jsonl). `INVALID` and
+   `UNSUPPORTED` inspection results cannot be made trainable by changing labels.
+   Do not replace computed digests with placeholder values.
+2. Prepare a pinned Claude Code profile. See
+   [the native examples](../examples/native) for profile structure. It must match
+   the agent and task requirements of your deployment.
+3. Stage checkpoint and reference directories on the GPU target. In its existing
+   training environment, load the actual local tokenizer with the same options as
+   the runtime and call `harborrl.rollout.runtime.tokenizer_fingerprint(tokenizer)`.
+   Its return values are `tokenizer_digest, template_digest`. This is an explicit
+   preparation step, not an operation performed by the wizard. Hashing a filename
+   or guessing an arbitrary 64-character value does not establish compatibility.
+4. Identify controller/GPU/runner Python executables, checkout paths, SSH aliases
+   and shared storage. Service origins must include their declared ports and be
+   reachable by the participating machines.
+5. For Sandbox, prepare the existing platform configuration and image bindings.
+   H-cluster users follow [the optional H practice](../practices/h_cluster/README.md)
+   and reference its site file. The core CLI never asks for H project/environment
+   identifiers or embeds private endpoints or credentials.
+
+## Generate
+
+```bash
+harborrl init --out-dir ./site-new
+harborrl init --answers my-answers.yaml --out-dir ./site-new
+```
+
+Interactive mode asks for deployment roles, existing inputs, model fingerprints,
+GPU layout and a few sampling settings, then previews both configurations and
+requires `yes` to publish. Entering no or EOF cancels. Non-terminal use requires
+`--answers`; missing required answers never fall back to prompting.
+
+Start from one of these complete answer templates and replace every `REPLACE_*`
+value and example path before running:
+
+- [embedded-local](../examples/options/embedded-local.answers.yaml): one machine,
+  local Harbor runner, colocated training/serving by default.
+- [service-ssh](../examples/options/service-ssh.answers.yaml): controller, SSH GPU
+  target and explicit SSH Docker workers.
+- [service-sandbox-local-runner](../examples/options/service-sandbox.answers.yaml):
+  controller and runner here, SSH GPU target, Sandbox task execution.
+
+Templates deliberately contain invalid digest placeholders. They cannot claim
+training readiness without your real inputs. Default one-GPU colocate is a
+configuration starting point, not a Qwen model memory-fit recommendation.
+
+Answers allow only `answers_version: 1`, `preset`, `training`, `deployment`, and
+optional `sandbox_config`. Overrides use the existing schema section/field names;
+unknown keys fail. No expressions or shell commands are evaluated. Gateway fields,
+shared run root, GPU budget and worker destinations are derived when only one
+side is provided. Contradictory explicit values fail. Supply matching origin URLs
+when changing ports. Paths in training overrides are relative to the **final
+output directory**, not the answers file. Deployment machine paths are absolute.
+
+The Sandbox preset can also describe remote runners through an answers file:
+set `training.harbor.runner_transport: ssh` and provide deployment rollout workers
+with `docker: false`. The builder derives training worker destinations and the
+first worker's runner Python. All configured interpreters still require preflight.
+
+`--probe-local` explicitly enables bounded local `nvidia-smi` UUID and current
+Python version queries. It also reads explicit SSH Host aliases (no wildcard,
+Match execution or Include expansion) and gives a parent-directory access hint.
+Missing tools and failed commands return `unknown`, not zero GPUs. Suggestions
+never silently change answers; no remote probe or write permission test occurs.
+
+The output directory must not exist, and its parent must exist. Publication uses
+an exclusive per-target lock, same-parent staging and a directory rename. Existing
+files are never overwritten. Failures clean up only this invocation's staging and
+lock. After an abrupt process termination, inspect any remaining `.NAME.init.lock`
+and staging directory before removing them; automatic stale-lock recovery is not
+attempted. The lock coordinates wizard processes, not arbitrary external writers.
+
+The bundle contains `config.yaml`, `deployment.yaml`, and `setup-manifest.json`.
+The manifest records schema versions, configuration digests, references and the
+offline validation scope, including deferred checks. It does not copy credentials.
+
+The CLI prints these next commands without executing them:
+
+```bash
+harborrl validate site-new/config.yaml --deployment site-new/deployment.yaml --check-files
+harborrl train site-new/config.yaml --deployment site-new/deployment.yaml --dry-run
+harborrl doctor site-new/config.yaml --deployment site-new/deployment.yaml
+```
+
+`doctor` performs live environment/connectivity checks. Actual training remains a
+separate action. Command examples use POSIX shell quoting.