Add SDK example environments

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ "*" ]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -26,6 +29,94 @@ jobs:
       - name: Run tests
         run: uv run --python ${{ matrix.python-version }} --all-extras pytest --cov --cov-report=''
 
+  templates:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        template: [blank, coding, cua, argument-hints]
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Create example environment
+        run: uv run hud init "${{ runner.temp }}/${{ matrix.template }}" --template "${{ matrix.template }}"
+
+      - name: Install example with the SDK from this checkout
+        working-directory: ${{ runner.temp }}/${{ matrix.template }}
+        run: |
+          uv build --wheel --no-create-gitignore --out-dir .hud-sdk "$GITHUB_WORKSPACE"
+          uv add --no-sync .hud-sdk/hud-*.whl
+          uv sync --all-extras
+          sed -i '/^RUN .*uv sync/i COPY .hud-sdk .hud-sdk' Dockerfile.hud
+          echo '!.hud-sdk/' >> .dockerignore
+          echo '!.hud-sdk/**' >> .dockerignore
+
+      - name: Run example checks
+        working-directory: ${{ runner.temp }}/${{ matrix.template }}
+        run: |
+          uv run --no-sync hud task list --source .
+          if [ -d tests ]; then
+            uv run --no-sync ruff format . --check
+            uv run --no-sync ruff check .
+            uv run --no-sync pytest -q
+          fi
+
+      - name: Build example image
+        working-directory: ${{ runner.temp }}/${{ matrix.template }}
+        run: docker build --file Dockerfile.hud --tag "hud-example:${{ matrix.template }}" .
+
+      - name: Start example image
+        env:
+          TEMPLATE: ${{ matrix.template }}
+        run: |
+          docker_args=()
+          if [ "$TEMPLATE" = coding ]; then
+            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+            docker_args+=(
+              --security-opt "seccomp=$GITHUB_WORKSPACE/hud/eval/docker-seccomp.json"
+              --security-opt systempaths=unconfined
+              --security-opt apparmor=unconfined
+            )
+          fi
+          docker run --detach --name hud-example --publish 8765:8765 --shm-size 2g "${docker_args[@]}" \
+            "hud-example:${{ matrix.template }}"
+
+      - name: Inspect example image
+        working-directory: ${{ runner.temp }}/${{ matrix.template }}
+        run: |
+          for attempt in {1..60}; do
+            if (echo > /dev/tcp/127.0.0.1/8765) 2>/dev/null \
+              && uv run --no-sync hud client info --url tcp://127.0.0.1:8765; then
+              exit 0
+            fi
+            sleep 1
+          done
+          docker logs hud-example
+          exit 1
+
+      - name: Run blank task lifecycle
+        if: matrix.template == 'blank'
+        working-directory: ${{ runner.temp }}/${{ matrix.template }}
+        run: |
+          uv run --no-sync hud task start 0 --source tasks.py --url tcp://127.0.0.1:8765
+          test "$(uv run --no-sync hud task grade 0 --source tasks.py --url tcp://127.0.0.1:8765 --answer 4)" = "1.0"
+
+      - name: Run coding task lifecycle
+        if: matrix.template == 'coding'
+        working-directory: ${{ runner.temp }}/${{ matrix.template }}
+        run: |
+          uv run --no-sync hud task start flask-4992 --source tasks.py --url tcp://127.0.0.1:8765
+          test "$(uv run --no-sync hud task grade flask-4992 --source tasks.py --url tcp://127.0.0.1:8765 --answer done)" = "0.0"
+
+      - name: Stop example image
+        if: always()
+        run: docker rm --force hud-example || true
+
   lint-ruff:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -62,8 +62,6 @@ hud/rl/checkpoints_test/
 
 docs/internal
 
-environments/
-
 experiments/
 .memories/
 

README.md

@@ -37,10 +37,12 @@ hud set HUD_API_KEY=your-key-here
 # or: export HUD_API_KEY=your-key-here
 ```
 
-Then scaffold your first environment:
+Then start from the coding environment, or choose another example environment:
 
 ```bash
 hud init my-env
+hud init my-desktop-env --template cua
+hud init my-custom-env --template blank
 ```
 
 ![Agent running on SheetBench](docs/src/images/trace_sheet.gif)
@@ -80,16 +82,6 @@ hud sync tasks my-taskset
 hud eval my-taskset --remote
 ```
 
-For local iteration, the same protocol works against a container on your laptop:
-
-```bash
-docker build -f Dockerfile.hud -t my-env .
-docker run -d --name run1 -p 8765:8765 my-env
-hud task start fix_bug --url tcp://127.0.0.1:8765
-hud task grade fix_bug --url tcp://127.0.0.1:8765 --answer "..."
-docker rm -f run1
-```
-
 → [Run & deploy](https://docs.hud.ai/v6/reference/runtime)
 
 ## Environments & templates

docs/skill.md

@@ -130,21 +130,18 @@ needed in the template. Cite [Capabilities](/v6/reference/capabilities).
 
 ---
 
-## Start from a template
+## Start from an example environment
 
-`hud init` scaffolds a new environment. Pass `--preset <id>` to start from a
-ready-made template instead of the blank scaffold (omit it for an interactive
-picker):
+`hud init` copies a complete environment project. Pass `--template <id>` to
+choose one, or omit it for the interactive picker:
 
 ```bash
-hud init my-env --preset browser
+hud init my-env --template coding
 ```
 
-Available presets: `blank`, `browser`, `cua` (computer-use desktop),
-`deepresearch`, `coding`, `ml`, `ml-triage`, `verilog`, `autonomous-businesses`,
-`gdpval`, `worldsim`, `robot`, `videogamebench`, and `arc-agi-3`. Each downloads
-a complete, runnable starting point you adapt — prefer it over hand-writing an
-environment from scratch. Cite [Quickstart](/v6/start/quickstart).
+Available examples: `coding`, `cua` (computer-use desktop), and `blank`. Adapt
+one of these projects instead of hand-writing an environment from scratch. Cite
+[Quickstart](/v6/start/quickstart).
 
 ---