Add SDK example environments

.github/workflows/ci.yml

@@ -26,7 +26,66 @@
       - name: Run tests
         run: uv run --python ${{ matrix.python-version }} --with=".[dev]" pytest --cov --cov-report=''
 
+  templates:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        template: [blank, coding, cua]
+
+    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 sync --all-extras
+          uv pip install -e "$GITHUB_WORKSPACE"
+
+      - 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
+        run: |
+          docker run --detach --name hud-example --publish 8765:8765 --shm-size 2g \
+            "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; then
+              uv run --no-sync hud client info --url tcp://127.0.0.1:8765
+              exit 0
+            fi
+            sleep 1
+          done
+          docker logs hud-example
+          exit 1
+
+      - name: Stop example image
+        if: always()
+        run: docker rm --force hud-example || true
+
   lint-ruff:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.gitignore

@@ -62,7 +62,9 @@ hud/rl/checkpoints_test/
 
 docs/internal
 
-environments/
+environments/*
+!environments/coding/
+!environments/cua/
 
 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)
@@ -85,8 +87,8 @@ 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 "..."
+hud task start fix_bug --source tasks.py --url tcp://127.0.0.1:8765
+hud task grade fix_bug --source tasks.py --url tcp://127.0.0.1:8765 --answer "..."
 docker rm -f run1
 ```