The hud run command executes MCP environments either locally via Docker or remotely via the HUD platform. Unlike hud dev which is for development, hud run is optimized for production execution.

​
Usage

hud run <TARGET> [OPTIONS] [-- DOCKER_ARGS...]

​
Arguments

​
target
string
required
Docker image reference (e.g., myorg/env:latest)
​
docker_args
array
Additional Docker arguments after -- (e.g., -e KEY=value)
Always use -- before Docker arguments to avoid conflicts with HUD options:
  • ✅ hud run image:tag -- -e KEY=value
  • ❌ hud run image:tag -e KEY=value

​
Options

​
--local
boolean
default:"false"
Run locally with Docker instead of remote execution
​
--remote
boolean
default:"true"
Explicitly run remotely (default behavior)
​
--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

​
Remote Execution (Default)

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