Skip to main content
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

ArgumentDescriptionDefault
DIRECTORYEnvironment directory (optional). (current)

​
Options

OptionDescriptionDefault
--image, -iDocker image name (overrides auto-detection)Auto-detected
--build, -bBuild image before startingfalse
--no-cacheForce rebuild without cachefalse
--transport, -tTransport protocol: http or stdiohttp
--port, -pHTTP server port (ignored for stdio)8765
--interactiveLaunch interactive tool testing interfacefalse
--no-reloadDisable hot-reload supervisionfalse
--verbose, -vShow detailed server logsfalse
--inspectorLaunch MCP Inspector (HTTP mode only)false
--no-logsDisable streaming Docker logsfalse
--full-reloadRestart entire container on file changes (not implemented)false

​
Examples

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

⌘I