hud dev

Hot-reload development server for MCP environments

The hud dev command provides development-time proxying for MCP environments, starting your image and exposing it over HTTP (default) or stdio.

Synopsis

hud dev [DIRECTORY] [OPTIONS]

Description

hud dev launches a lightweight MCP proxy that runs your Docker image and forwards MCP traffic. It auto-detects or builds your image, mounts your project directory, and optionally opens an inspector or interactive tool runner.

Key Features:

• Auto-detection: Determines image from [tool.hud.image] or dir-name:dev
• Project mount: Mounts your project at /app (sets PYTHONPATH=/app)
• Interactive testing: TUI for calling tools (HTTP transport only)
• HTTP/Stdio protocols: Choose transport method (http default)
• Inspector support: Launch MCP Inspector (HTTP mode)
• Per-connection containers: Each client gets its own container

Arguments

Argument	Description	Default
DIRECTORY	Environment directory (optional)	. (current)

Options

Option	Description	Default
--image, -i	Docker image name (overrides auto-detection)	Auto-detected
--build, -b	Build image before starting	false
--no-cache	Force rebuild without cache	false
--transport, -t	Transport protocol: http or stdio	http
--port, -p	HTTP server port (ignored for stdio)	8765
--interactive	Launch interactive tool testing interface	false
--no-reload	Disable hot-reload supervision	false
--verbose, -v	Show detailed server logs	false
--inspector	Launch MCP Inspector (HTTP mode only)	false
--no-logs	Disable streaming Docker logs	false
--full-reload	Restart entire container on file changes (not implemented)	false

Examples

Auto-Detection Mode (Recommended)

hud dev

Build and Start

hud dev --build

Specific Directory

hud dev environments/my-env --build

Custom Image

hud dev . --image my-custom-env:dev --build

HTTP Mode with Inspector

hud dev . --build --transport http --inspector

Stdio Mode

hud dev . --build --transport stdio

Clean Rebuild

hud dev . --build --no-cache

Verbose Logging

hud dev . --build --verbose

Interactive Testing (HTTP only)

hud dev . --build --interactive

Interactive mode disables log streaming and hot-reload supervision to provide a clean UI.

How It Works

1. Image Resolution:

   • Reads pyproject.toml [tool.hud.image]
   • Auto-generates dir-name:dev if absent; writes it back on build
   • Uses --image override if provided

2. Container Startup:

   • Runs your image with its original CMD (the container controls reload behavior)
   • Mounts your project at /app and sets PYTHONPATH=/app
   • For HTTP transport, the proxy hosts http://localhost:<port>/mcp

3. Proxy Server:

   • Each client connection gets its own container
   • Inspector and interactive UI are available in HTTP mode

4. Hot-Reload:

   • Depends on your container CMD (templates include --reload flags)
   • For best results, separate the restartable MCP controller from any long-lived backend

Process Separation Architecture

For stateful environments, hud dev supports a critical design pattern: separating the MCP server from the environment process. This separation enables hot-reload without losing state.

Why Separation Matters:

• MCP server can restart instantly for code changes
• Environment state (browsers, databases, games) persists
• Development is faster without constant state resets

Example Architecture:

Connection Methods:

• Unix sockets (recommended for local dev)
• TCP/HTTP endpoints
• gRPC services
• Shared memory/IPC

Separating the MCP server (restartable) from the backend (stateful) enables code reloads without losing state. See the browser template for a full example.

File Mounting

Project directory is mounted as /app inside the container:

Local: ./                   → Container: /app/
Local: ./controller/        → Container: /app/controller/
Local: ./environment/       → Container: /app/environment/

Transport Modes

HTTP Transport (Default)

hud dev . --transport http --port 8765

Benefits:

• Web browser access and MCP Inspector
• Multiple simultaneous connections
• Easier debugging

URL: http://localhost:8765/mcp

Stdio Transport

hud dev . --transport stdio

Benefits:

• Direct MCP protocol, lower latency
• Single connection focused

Integration Examples

Cursor Integration

1. Start development server:
   hud dev . --build --transport http --port 8765
   
2. Add to Cursor’s MCP config:
   {
     "mcpServers": {
       "my-dev-env": {
         "url": "http://localhost:8765/mcp"
       }
     }
   }
   
3. Edit files — changes apply immediately based on your container’s reload behavior.

Testing During Development

# Quick inspection (optional)
hud analyze my-env:dev

# Deep check (only when broken)
hud debug my-env:dev

MCP Inspector

hud dev . --build --inspector

Opens an inspector that shows:

• Available tools and schemas
• Real-time tool calls and protocol messages

Troubleshooting

• Use --verbose to see container logs
• If container never starts: run hud debug <image>
• Port conflicts: choose a new --port

See Also

• hud init — Create new environments
• hud build — Build production images
• hud analyze — Inspect tools
• hud debug — Validate environment
• hud run — Run locally/remotely
• Deploy — Push to GitHub and deploy