Skip to main content
The hud run command executes MCP servers in three ways: (1) Python module/file (decorator‑based), (2) arbitrary command, or (3) Docker image (local/remote). Unlike hud dev, hud run is optimized for execution, not hot‑reload.

​
Usage

# Python module or file (decorator-based)
hud run controller[:attr] [OPTIONS]
hud run path/to/server.py[:attr] [OPTIONS]

# Arbitrary command
hud run --cmd "python -m controller" [OPTIONS]

# Docker image (supports Docker args after --)
hud run <IMAGE> [OPTIONS] [-- DOCKER_ARGS...]

​
Arguments

​
target
string
required
Python module/file (e.g., controller or controller:server) or a Docker image (e.g., myorg/env:latest)
​
docker_args
array
Additional Docker arguments (accepted after the image)
Docker arguments are passed positionally after the image in this command form.

​
Options

​
--local
boolean
default:"false"
Run locally with Docker instead of remote execution
​
--remote
boolean
default:"false"
Explicitly run remotely (default behavior if neither —local nor —remote is set)
​
--transport
string
default:"stdio"
Transport protocol: stdio or http. Short: -t
​
--port
integer
default:"8765"
Port for HTTP transport (ignored for stdio). Short: -p
​
--url
string
default:"https://mcp.hud.so/v3/mcp"
Remote MCP server URL
​
--api-key
string
API key for remote server (defaults to HUD_API_KEY env var)
​
--run-id
string
Run ID for tracking (remote only)
​
--verbose
boolean
default:"false"
Show detailed output. Short: -v
​
--interactive
boolean
default:"false"
Launch interactive testing mode (HTTP transport only; local Docker only)
​
--reload
boolean
default:"false"
Auto-reload when files change (Python mode only)
​
--watch
array
Directories to watch when using --reload (Python mode)
​
--cmd
string
Run an arbitrary command as an MCP server (e.g., python -m controller)

​
Python Mode (Decorator-based)

Run a Python module, package, or file containing an MCP server (default attribute mcp; override with module:attr). 
# Run module or file (stdio by default)
hud run controller
hud run controller:mcp
hud run server.py:mcp

# Auto-reload on changes (watches module/package)
hud run controller --reload
hud run controller --reload --watch controller tools

# HTTP transport
hud run controller -t http -p 8765

​
Remote Execution (Default for Docker)

By default, hud run executes your Docker image on the HUD platform’s remote infrastructure. This provides:
  • Scalability: Run hundreds of concurrent instances
  • Resource Management: Automatic container lifecycle management
  • Monitoring: Live telemetry and performance metrics
  • Geographic Distribution: Global edge deployment

​
Remote Examples

# Basic remote execution
hud run hudpython/text-2048:latest

# With environment variables
hud run myorg/server:v1 -- -e API_KEY=secret -e DEBUG=true

# HTTP transport with custom port
hud run myorg/server:v1 --transport http --port 9000

# Custom remote URL and API key
hud run my-image:latest --url https://custom.mcp.server --api-key my-key

# With run tracking
hud run production-env:v1.0 --run-id "deploy-$(date +%Y%m%d)"

​
Authentication

Remote execution requires authentication via API key: 
# Set environment variable (recommended)
export HUD_API_KEY=your-api-key-here
hud run my-image:latest

# Or pass directly (less secure)
hud run my-image:latest --api-key your-api-key-here

​
Run Tracking

Use --run-id to track specific execution instances: 
hud run my-image:latest --run-id "experiment-001"

​
Local Execution

Use --local to run the image locally with Docker: 
# Basic local execution
hud run hudpython/text-2048:latest --local

# With Docker arguments
hud run myorg/server:v1 --local -- -e API_KEY=secret -v /data:/app/data

# HTTP transport locally
hud run myorg/server:v1 --local --transport http --port 8080

# With memory limits and volumes
hud run my-env:latest --local -- --memory 2g -v $(pwd)/data:/app/data
Local execution is useful for:
  • Development and testing
  • Environments without internet access
  • Custom Docker configurations
  • Debugging before remote deployment

​
Transport Modes

​
Stdio Transport (Default)

hud run my-image:latest --transport stdio
Characteristics:
  • Direct JSON-RPC over stdin/stdout
  • Single client connection
  • Lower latency
  • MCP protocol native

​
HTTP Transport

hud run my-image:latest --transport http --port 8765
Characteristics:
  • HTTP proxy at specified port
  • Multiple concurrent connections
  • Web-compatible
  • Inspector support

​
Docker Arguments

Pass Docker arguments after -- separator: 
# Environment variables
hud run my-image:latest -- -e DEBUG=true -e API_KEY=secret

# Volume mounts
hud run my-image:latest -- -v /host/data:/container/data

# Network settings
hud run my-image:latest -- --network host

# Memory limits
hud run my-image:latest -- --memory 2g

# Combined arguments
hud run my-image:latest -- -e API_KEY=secret -v /data:/app/data --memory 1g
The -- separator is required to distinguish HUD options from Docker arguments.

​
Environment Variables

VariableDescriptionDefault
HUD_MCP_URLRemote MCP server URLhttps://mcp.hud.so/v3/mcp
HUD_API_KEYAPI key for remote authenticationrequired for remote

​
Comparison with Other Commands

CommandPurposeHot-reloadTarget Use Case
hud devDevelopment with auto-restart✅ YesLocal development iteration
hud runProduction execution❌ NoProduction workloads, testing
hud debugEnvironment validation❌ NoDebugging and validation

​
Examples

​
Basic Usage

# Run remotely (default)
hud run hudpython/text-2048:latest

# Run locally for testing
hud run hudpython/text-2048:latest --local

# Verbose output for debugging
hud run my-image:latest --local --verbose

​
Production Deployment

# Remote execution with tracking
export HUD_API_KEY=your-production-key
hud run production-env:v1.0 --run-id "prod-deploy-$(date +%s)"

# With environment configuration
hud run production-env:v1.0 --run-id "prod-$(git rev-parse --short HEAD)" -- \
  -e DATABASE_URL=postgres://... \
  -e REDIS_URL=redis://... \
  -e LOG_LEVEL=info

​
Development Testing

# Test locally before remote deployment
hud run my-env:dev --local -- -e DEBUG=true

# Test with HTTP transport
hud run my-env:dev --local --transport http --port 9000

# Test with custom data volume
hud run my-env:dev --local -- -v $(pwd)/test-data:/app/data

​
CI/CD Integration

# GitHub Actions example
- name: Run HUD environment
  env:
    HUD_API_KEY: ${{ secrets.HUD_API_KEY }}
  run: |
    # Pull latest
    hud pull myorg/env:latest --yes
    
    # Run tests
    hud run myorg/env:latest --run-id "ci-${{ github.sha }}"

​
Error Handling

hud run provides clear error messages for common issues:
  • Missing image: Suggests available images or build commands
  • Authentication failure: Guides through API key setup
  • Port conflicts: Suggests alternative ports
  • Docker errors: Shows Docker-specific troubleshooting

​
See Also

⌘I