hud-python 0.4.56__tar.gz → 0.4.58__tar.gz

{hud_python-0.4.56 → hud_python-0.4.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.4.56
+Version: 0.4.58
 Summary: SDK for the HUD platform.
 Project-URL: Homepage, https://github.com/hud-evals/hud-python
 Project-URL: Bug Tracker, https://github.com/hud-evals/hud-python/issues

{hud_python-0.4.56 → hud_python-0.4.58}/environments/README.md

@@ -495,7 +495,7 @@ from hud.agents import ClaudeAgent
 from hud.clients import MCPClient
 
 async def main():
-    # `trace` captures *everything* that happens and sends it to hud.so
+    # `trace` captures *everything* that happens and sends it to hud.ai
     with hud.trace("local_test"):
         task = Task(
             prompt="Complete the task",
@@ -524,7 +524,7 @@ async def main():
 asyncio.run(main())
 ```
 
-The `trace` context manager sends a full timeline of agent actions, tool calls, and rewards to hud.so – perfect for debugging.
+The `trace` context manager sends a full timeline of agent actions, tool calls, and rewards to hud.ai – perfect for debugging.
 
 See `examples/01_hello_2048.py` and `examples/task_with_setup_eval.py` for larger end-to-end demos.
 
@@ -532,7 +532,7 @@ See `examples/01_hello_2048.py` and `examples/task_with_setup_eval.py` for large
 
 ## Phase 4 – Remote Deployment & HUD Runner
 
-**Goal →** the exact same image runs in parallel on hundreds of instances, and exposes more telemetry so the hud.so can visualise the whole lifecycle.
+**Goal →** the exact same image runs in parallel on hundreds of instances, and exposes more telemetry so the hud.ai can visualise the whole lifecycle.
 
 ### 1. Publish your image
 
@@ -595,11 +595,11 @@ async def initialize_environment(session=None, progress_token=None):
     await send(100, "ready")
 ```
 
-Those messages are displayed live on hud.so alongside resource graphs – perfect feedback while you wait.
+Those messages are displayed live on hud.ai alongside resource graphs – perfect feedback while you wait.
 
 ### 4. Live telemetry (`telemetry://live`) (Optional)
 
-Expose a resource named `telemetry://live` exactly like in `environments/browser/src/hud_controller/server.py` to return live url to be displayed on hud.so.
+Expose a resource named `telemetry://live` exactly like in `environments/browser/src/hud_controller/server.py` to return live url to be displayed on hud.ai.
 
 Once all of the above works you can unleash *hundreds* of concurrent agents on your new environment.
 

hud_python-0.4.58/environments/browser/browser-base/README.md

@@ -0,0 +1,58 @@
+# Browser Base Image
+
+Base Docker image for browser environments with Playwright, Chromium, and VNC support.
+
+## Build
+
+```bash
+docker build -t browser-base:latest .
+```
+
+## Test with VNC Access
+
+### 1. Start the container
+
+```bash
+docker run -it --rm \
+  -p 6080:6080 \
+  -p 5900:5900 \
+  -e DISPLAY=:1 \
+  browser-base:latest \
+  bash
+```
+
+### 2. Inside the container, start display servers
+
+```bash
+Xvfb :1 -screen 0 1920x1080x24 > /dev/null 2>&1 &
+x11vnc -display :1 -nopw -listen 0.0.0.0 -forever > /dev/null 2>&1 &
+/usr/share/novnc/utils/novnc_proxy --vnc localhost:5900 --listen 6080 > /dev/null 2>&1 &
+```
+
+### 3. Test Playwright
+
+```bash
+python3 -c "
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=False)
+    page = browser.new_page()
+    page.goto('https://example.com')
+    print('Title:', page.title())
+    input('Press Enter to close...')
+    browser.close()
+"
+```
+
+### 4. View in browser
+
+Open `http://localhost:6080/vnc.html` to see Chromium running.
+
+## What's Included
+
+- Ubuntu 24.04
+- Desktop environment (Xvfb, x11vnc, noVNC, xfce4)
+- Node.js & npm
+- Python 3 with uv package manager
+- Playwright with Chromium
+- Development tools (git, curl, wget, etc.)

{hud_python-0.4.56 → hud_python-0.4.58}/environments/browser/server/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "HUD Browser MCP Server"
 requires-python = ">=3.11,<3.14"
 dependencies = [
-    "hud-python>=0.4.54",
+    "hud-python>=0.4.58",
     "httpx",
     "playwright",
     "pyautogui",

hud_python-0.4.58/environments/rubrics/README.md

@@ -0,0 +1,239 @@
+# SEC EDGAR Rubrics Environment
+
+SEC filing research environment powered by the SEC EDGAR database for accessing company filings and financial data, with rubric-based evaluation for structured grading provided by [The LLM Data Company](https://llmdata.com).
+
+See [docs](https://docs.hud.so/build-environments) for the complete environment design workflow.
+
+## Architecture
+
+**`environment/`** - Manages SEC EDGAR and web search integration
+- Uses the edgartools Python library to access SEC filing data
+- Integrates with Exa API for supplementary web search capabilities
+- Exposes HTTP endpoints for research workflows with exponential backoff for rate limiting
+
+**`server/`** - Wraps data in MCP tools
+- Provides research tools for agents to access SEC filings, financial data, and web search
+- Agents and tasks interact only with these tools
+
+**Why separate?** Edit tools for the agent or tasks without restarting the environment backend.
+
+## Tools
+
+### SEC EDGAR Tools
+- **`setup()`** - Initialize the environment and reset state.
+- **`search_company(query: str)`** - Search for a company by ticker symbol or name. Returns company information including ticker, name, and CIK.
+- **`get_filings(ticker?: str, form_type?: str, limit?: int, cutoff_date?: str)`** - Get SEC filings. When `ticker` is provided, returns company-specific filings. Otherwise, returns global recent filings. Can filter by form type (e.g., "10-K", "10-Q", "8-K"), limit results, and filter by date (YYYY-MM-DD).
+- **`get_filing_content(filing_url: str)`** - Fetch the full text content of a specific SEC filing from its URL.
+- **`get_financial_data(ticker: str, accession_number: str)`** - Extract financial statements and key metrics from a 10-K or 10-Q filing. Returns income statement, balance sheet, cash flow, and other financial data.
+- **`get_segment_data(ticker: str, accession_number: str)`** - Extract segment-level financial data from a 10-K or 10-Q filing for companies with multiple business segments.
+- **`get_filing_sections(ticker: str, accession_number: str)`** - Extract specific sections from a 10-K or 10-Q filing (e.g., Business, Risk Factors, MD&A).
+
+### Web Search Tools
+- **`web_search(query: str)`** - Search the web using Exa API. Returns titles and URLs of relevant results.
+- **`web_fetch(url: str)`** - Fetch and extract content from a web URL. Returns summary, highlights, and full content.
+
+### Evaluation Tools
+- **`answer(final_answer: str)`** - Submit the final research answer.
+- **`evaluate(rubric: list[dict])`** - Evaluate submitted answer using a structured rubric with weighted requirements.
+
+### Rubric-Based Evaluation
+
+The `evaluate` tool uses The LLM Data Company's [rubric](https://github.com/The-LLM-Data-Company/rubric/) package to grade answers against structured criteria with autograders.
+
+## Setup
+
+### Environment Variables
+
+The environment requires several API keys and configuration:
+
+**Required:**
+- `EDGAR_IDENTITY` - Your identity for SEC EDGAR access (required by SEC regulations)
+  - Format: `"Your Name your.email@example.com"`
+
+**Optional:**
+- `EXA_API_KEY` - For web search and content fetching capabilities (if using web_search/web_fetch tools)
+- `HUD_API_KEY` - For HUD telemetry and tracing
+- `ANTHROPIC_API_KEY` - For Claude agent (if using Claude)
+- `OPENAI_API_KEY` - For rubric evaluation (if using OpenAI-based autograders)
+
+Add these to your .env before running `hud eval`:
+```bash
+export EDGAR_IDENTITY="Your Name your.email@example.com"
+export EXA_API_KEY="your-exa-key" # optional, for web search
+export ANTHROPIC_API_KEY="your-anthropic-key" # only if using an Anthropic model
+export OPENAI_API_KEY="your-openai-key"
+# Optional
+export HUD_API_KEY="your-hud-key"
+```
+
+## Development
+
+```bash
+# Terminal 1 - Environment backend
+cd environment
+export EDGAR_IDENTITY="Your Name your.email@example.com"
+export EXA_API_KEY="your-exa-key"  # optional, for web search
+uv run uvicorn server:app --reload
+
+# Terminal 2 - MCP server
+cd server
+uv run hud dev
+```
+
+The environment includes exponential backoff for rate limiting, so API calls will automatically retry on 429 errors.
+
+In general, we recommend starting work on the environment backend first, then developing the MCP server to expose the right things to the agent.
+
+For complex environments that require many dependencies, we recommend running `hud dev` in the environment root:
+```bash
+cd ..
+hud dev
+```
+
+## Tasks & Evaluation
+
+```bash
+# Build first in the global folder with the Dockerfile (creates rubrics:latest)
+hud build
+```
+
+Your `tasks.json` uses `docker run` to launch the environment:
+
+```json
+{
+  "prompt": "Analyze Tesla's FY2024 10-K filing...",
+  "mcp_config": {
+    "local": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "rubrics:latest"]
+    }
+  },
+  "evaluate_tool": {
+    "name": "evaluate",
+    "arguments": {
+      "rubric": [...]
+    }
+  }
+}
+```
+
+**Note:** Export environment variables before running. The Docker container will inherit them from your shell.
+
+**Commands:**
+```bash
+# Build first
+hud build
+
+# Test task locally
+export EDGAR_IDENTITY="Your Name your.email@example.com"
+export EXA_API_KEY="your-exa-key"  # optional, for web search
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export OPENAI_API_KEY="your-openai-key"
+hud eval tasks.json --max-steps 25
+
+# Push environment for remote running
+hud push
+
+# Production RL training
+hud rl tasks.json  # Auto-converts docker→remote, builds & pushes if needed
+```
+
+## Publishing Your Environment
+
+Once your environment is ready, you can share it with the community:
+
+### 1. Push to Registry
+```bash
+# Build and push your environment (requires docker hub login and hud api key)
+hud build
+hud push
+```
+
+### 2. Create a Dataset
+
+Create a dataset on HuggingFace with your tasks:
+
+**Option A: Upload manually**
+1. Upload your `tasks.json` to HuggingFace
+2. Make sure it's **public** to appear on leaderboards
+
+**Option B: Use the SDK**
+```python
+from hud.datasets import save_tasks
+import json
+
+# Load your tasks
+with open("tasks.json") as f:
+    tasks = json.load(f)
+
+# Push to HuggingFace
+save_tasks(tasks, repo_id="your-org/your-dataset")
+```
+
+### 3. Run and Track Performance
+
+```bash
+# Run Claude on your benchmark
+hud eval "your-org/your-dataset" --agent claude
+
+# View results at:
+# hud.so/leaderboards/your-org/your-dataset
+```
+
+**Note**: Only public HuggingFace datasets appear as leaderboards!
+
+📚 Learn more: [Creating Benchmarks](https://docs.hud.so/evaluate-agents/create-benchmarks) | [Leaderboards](https://docs.hud.so/evaluate-agents/leaderboards)
+
+## Example Research Workflow
+
+```python
+# Initialize environment
+setup()
+
+# Agent searches for a company
+company_info = search_company("TSLA")
+# Returns: [{"ticker": "TSLA", "name": "Tesla Inc", "cik": "1318605"}]
+
+# Agent gets recent filings
+filings = get_filings(ticker="TSLA", form_type="10-K", limit=1)
+# Returns: [{"filing_date": "2024-01-01", "form_type": "10-K", "accession_number": "...", "filing_url": "..."}]
+
+# Agent extracts financial data
+financial_data = get_financial_data(ticker="TSLA", accession_number=filings[0]["accession_number"])
+# Returns: {"has_financials": True, "financial_data": {...income statement, balance sheet, etc...}}
+
+# Agent gets specific sections from the filing
+sections = get_filing_sections(ticker="TSLA", accession_number=filings[0]["accession_number"])
+# Returns: {"sections": {"business": "...", "risk_factors": "...", "mda": "..."}}
+
+# Agent uses web search for additional context
+search_results = web_search("Tesla FY2024 revenue analysis")
+# Returns: [{"title": "...", "url": "..."}]
+
+# Agent fetches web content
+web_content = web_fetch(search_results[0]["url"])
+# Returns: "=== SUMMARY ===\n...\n=== KEY HIGHLIGHTS ===\n...\n=== FULL CONTENT ===\n..."
+
+# Agent submits final answer
+answer("Based on Tesla's FY2024 10-K, revenue was $96.8B...")
+
+# Evaluate answer using rubric
+result = evaluate(rubric=[
+    {"requirement": "Correctly states FY2024 revenue", "weight": 15},
+    {"requirement": "Provides segment breakdown", "weight": 5},
+])
+# Returns: {"reward": float, "info": {"report": [...]}, "done": True}
+```
+
+## Dependencies
+
+- **edgartools**: Python library for accessing SEC EDGAR data
+- **fastapi**: Web framework for the environment server
+- **httpx**: HTTP client for API calls
+- **rubric**: LLM Data Company's rubric evaluation package
+- **Exa API**: Web search and content extraction (optional, for web_search/web_fetch tools)
+
+## Acknowledgments
+
+* [EdgarTools](https://github.com/dgunning/edgartools) - Python library to access SEC EDGAR
+* [SEC EDGAR MCP](https://github.com/stefanoamorelli/sec-edgar-mcp) - Rich OSS SEC MCP server

{hud_python-0.4.56 → hud_python-0.4.58}/environments/rubrics/environment/pyproject.toml

@@ -1,13 +1,14 @@
 [project]
 name = "rubrics-environment"
 version = "0.1.0"
-description = "Backend service for Rubrics environment"
+description = "Backend service for Rubrics environment with SEC EDGAR integration"
 requires-python = ">=3.11"
 dependencies = [
     "fastapi>=0.104.1",
     "uvicorn[standard]>=0.24.0",
     "httpx>=0.24.0",
-    "rubric>=1.1.7",
+    "rubric==1.1.8",
+    "edgartools>=4.21.3",
 ]
 
 [build-system]

{hud_python-0.4.56 → hud_python-0.4.58}/environments/rubrics/pyproject.toml

@@ -16,4 +16,4 @@ image = "rubrics:dev"
 allow-direct-references = true
 
 [tool.hatch.build.targets.wheel]
-packages = [ "controller", "environment",]
+packages = [ "server", "environment",]

{hud_python-0.4.56 → hud_python-0.4.58}/hud/cli/__init__.py

@@ -253,10 +253,23 @@ def debug(
         else:
             # Assume it's an image name
             image = first_param
-            from .utils.docker import build_run_command
+            from .utils.docker import create_docker_run_command
+
+            # For image mode, check if there's a .env file in current directory
+            # and use it if available (similar to hud dev behavior)
+            cwd = Path.cwd()
+            if (cwd / ".env").exists():
+                # Use create_docker_run_command to load .env from current directory
+                command = create_docker_run_command(
+                    image,
+                    docker_args=docker_args,
+                    env_dir=cwd,  # Load .env from current directory
+                )
+            else:
+                # No .env file, use basic command without env loading
+                from .utils.docker import build_run_command
 
-            # Image-only mode: do not auto-inject local .env
-            command = build_run_command(image, docker_args)
+                command = build_run_command(image, docker_args)
     else:
         console.print(
             "[red]Error: Must specify a directory, Docker image, --config, or --cursor[/red]"
@@ -741,14 +754,14 @@ def remove(
 
 @app.command()
 def init(
-    name: str = typer.Argument(None, help="Environment name (default: current directory name)"),
+    name: str = typer.Argument(None, help="Environment name (default: chosen preset name)"),
     preset: str | None = typer.Option(
         None,
         "--preset",
         "-p",
         help="Preset to use: blank, deep-research, browser, rubrics. If omitted, you'll choose interactively.",  # noqa: E501
     ),
-    directory: str = typer.Option(".", "--dir", "-d", help="Target directory"),
+    directory: str = typer.Option(".", "--dir", "-d", help="Parent directory for the environment"),
     force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
 ) -> None:
     """🚀 Initialize a new HUD environment with minimal boilerplate.
@@ -760,8 +773,8 @@ def init(
     - Required setup/evaluate tools
 
     Examples:
-        hud init                    # Use current directory name
-        hud init my-env             # Create in ./my-env/
+        hud init                    # Choose preset interactively, create ./preset-name/
+        hud init my-env             # Create new directory ./my-env/
         hud init my-env --dir /tmp  # Create in /tmp/my-env/
     """
     create_environment(name, directory, force, preset)

{hud_python-0.4.56 → hud_python-0.4.58}/hud/cli/dev.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import importlib
 import importlib.util
 import logging
@@ -13,6 +14,8 @@ import threading
 from pathlib import Path
 from typing import Any
 
+import typer
+
 from hud.utils.hud_console import HUDConsole
 
 hud_console = HUDConsole()
@@ -26,6 +29,7 @@ def show_dev_server_info(
     interactive: bool,
     env_dir: Path | None = None,
     new: bool = False,
+    docker_mode: bool = False,
 ) -> str:
     """Show consistent server info for both Python and Docker modes.
 
@@ -54,7 +58,15 @@ def show_dev_server_info(
     if transport == "http":
         hud_console.section_title("Quick Links")
         hud_console.info(f"{hud_console.sym.ITEM} Docs: http://localhost:{port}/docs")
-        hud_console.info(f"{hud_console.sym.ITEM} Cursor: {cursor_deeplink}")
+        hud_console.info(f"{hud_console.sym.ITEM} Cursor:")
+        # Display the Cursor link on its own line to prevent wrapping
+        hud_console.link(cursor_deeplink)
+
+        # Show eval endpoint if in Docker mode
+        if docker_mode:
+            hud_console.info(
+                f"{hud_console.sym.ITEM} Eval API: http://localhost:{port}/eval (POST)"
+            )
 
         # Check for VNC (browser environment)
         if env_dir and (env_dir / "environment" / "server.py").exists():
@@ -237,7 +249,7 @@ async def run_mcp_module(
 
                 from hud.cli.flows.dev import create_dynamic_trace
 
-                live_trace_url = await create_dynamic_trace(
+                _, live_trace_url = await create_dynamic_trace(
                     mcp_config=local_mcp_config,
                     build_status=False,
                     environment_name=mcp_server.name or "mcp-server",
@@ -510,6 +522,9 @@ def run_docker_dev_server(
     new: bool = False,
 ) -> None:
     """Run MCP server in Docker with volume mounts, expose via local HTTP proxy."""
+    import atexit
+    import signal
+
     import typer
     import yaml
 
@@ -522,6 +537,69 @@ def run_docker_dev_server(
 
     cwd = Path.cwd()
 
+    # Container name will be set later and used for cleanup
+    container_name: str | None = None
+    cleanup_done = False
+
+    def cleanup_container() -> None:
+        """Clean up Docker container on exit."""
+        nonlocal cleanup_done
+        if cleanup_done or not container_name:
+            return
+
+        cleanup_done = True
+        hud_console.debug(f"Cleaning up container: {container_name}")
+
+        # Check if container is still running
+        try:
+            result = subprocess.run(  # noqa: S603
+                ["docker", "ps", "-q", "-f", f"name={container_name}"],  # noqa: S607
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                text=True,
+                timeout=5,
+            )
+            if not result.stdout.strip():
+                # Container is not running, just try to remove it
+                subprocess.run(  # noqa: S603
+                    ["docker", "rm", "-f", container_name],  # noqa: S607
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=5,
+                )
+                return
+        except Exception:  # noqa: S110
+            pass
+
+        try:
+            # First try to stop gracefully
+            subprocess.run(  # noqa: S603
+                ["docker", "stop", container_name],  # noqa: S607
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+            )
+            hud_console.debug(f"Container {container_name} stopped successfully")
+        except subprocess.TimeoutExpired:
+            # Force kill if stop times out
+            hud_console.debug(f"Container {container_name} stop timeout, forcing kill")
+            with contextlib.suppress(Exception):
+                subprocess.run(  # noqa: S603
+                    ["docker", "kill", container_name],  # noqa: S607
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=5,
+                )
+
+    # Set up signal handlers for cleanup
+    def signal_handler(signum: int, frame: Any) -> None:
+        cleanup_container()
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, signal_handler)
+    if sys.platform != "win32":
+        signal.signal(signal.SIGHUP, signal_handler)
+
     # Find environment directory (current or parent with hud.lock.yaml)
     env_dir = cwd
     lock_path = env_dir / "hud.lock.yaml"
@@ -562,10 +640,14 @@ def run_docker_dev_server(
     base_name = image_name.replace(":", "-").replace("/", "-")
     container_name = f"{base_name}-dev-{pid}"
 
+    # Register cleanup function with atexit
+    atexit.register(cleanup_container)
+
     # Build docker run command with volume mounts and folder-mode envs
     from .utils.docker import create_docker_run_command
 
     base_args = [
+        "--rm",  # Automatically remove container when it stops
         "--name",
         container_name,
         "-v",
@@ -608,7 +690,7 @@ def run_docker_dev_server(
                     "headers": {},
                 }
             }
-            live_trace_url = _asy.run(
+            _, live_trace_url = _asy.run(
                 create_dynamic_trace(
                     mcp_config=local_mcp_config,
                     build_status=True,
@@ -643,6 +725,7 @@ def run_docker_dev_server(
             interactive=interactive,
             env_dir=env_dir,
             new=new,
+            docker_mode=True,
         )
         hud_console.dim_info(
             "",
@@ -661,13 +744,38 @@ def run_docker_dev_server(
     # Create and run proxy with HUD helpers
     async def run_proxy() -> None:
         from fastmcp import FastMCP
+        from fastmcp.server.proxy import ProxyClient
+
+        # Create ProxyClient without custom log handler since we capture Docker logs directly
+        proxy_client = ProxyClient(mcp_config, name="HUD Docker Dev Proxy")
+
+        # Extract container name from docker args and store for logs endpoint
+        docker_cmd = mcp_config["docker"]["args"]
+        container_name = None
+        for i, arg in enumerate(docker_cmd):
+            if arg == "--name" and i + 1 < len(docker_cmd):
+                container_name = docker_cmd[i + 1]
+                break
 
-        # Create FastMCP proxy to Docker stdio
-        fastmcp_proxy = FastMCP.as_proxy(mcp_config, name="HUD Docker Dev Proxy")
+        if container_name:
+            # Store container name for logs endpoint to use
+            os.environ["_HUD_DEV_DOCKER_CONTAINER"] = container_name
+            hud_console.debug(f"Docker container: {container_name}")
+
+        # Store the docker mcp_config for the eval endpoint
+        import json
+
+        os.environ["_HUD_DEV_DOCKER_MCP_CONFIG"] = json.dumps(mcp_config)
+
+        # Create FastMCP proxy using the ProxyClient
+        fastmcp_proxy = FastMCP.as_proxy(proxy_client)
 
         # Wrap in MCPServer to get /docs and REST wrappers
         proxy = MCPServer(name="HUD Docker Dev Proxy")
 
+        # Enable logs endpoint on HTTP server
+        os.environ["_HUD_DEV_LOGS_PROVIDER"] = "enabled"
+
         # Import all tools from the FastMCP proxy
         await proxy.import_server(fastmcp_proxy)
 
@@ -693,7 +801,15 @@ def run_docker_dev_server(
         asyncio.run(run_proxy())
     except KeyboardInterrupt:
         hud_console.info("\n\nStopping...")
+        cleanup_container()
         raise typer.Exit(0) from None
+    except Exception:
+        # Ensure cleanup happens on any exception
+        cleanup_container()
+        raise
+    finally:
+        # Final cleanup attempt
+        cleanup_container()
 
 
 def run_mcp_dev_server(
@@ -712,6 +828,20 @@ def run_mcp_dev_server(
     docker_args = docker_args or []
     cwd = Path.cwd()
 
+    # Find an available port if not using stdio transport
+    if not stdio:
+        from hud.cli.utils.logging import find_free_port
+
+        actual_port = find_free_port(port)
+        if actual_port is None:
+            hud_console.error(f"No available ports found starting from {port}")
+            raise typer.Exit(1)
+
+        if actual_port != port:
+            hud_console.info(f"Port {port} is in use, using port {actual_port} instead")
+
+        port = actual_port
+
     # Auto-detect Docker mode if Dockerfile present and no module specified
     if not docker and module is None and should_use_docker_mode(cwd):
         hud_console.note("Detected Dockerfile - using Docker mode with volume mounts")