The hud init command creates a new HUD environment from scratch with all the essential files needed to build, test, and deploy an MCP server.

​
Usage

hud init [NAME] [OPTIONS]

​
Arguments

​
name
string
Environment name. If not provided, uses the current directory name.

​
Options

​
--dir
string
default:"."
Target directory where the environment will be created. Short: -d
​
--force
boolean
default:"false"
Overwrite existing files if they exist. Short: -f

​
What It Creates

The command generates a minimal but complete HUD environment structure: 
my-env/
├── Dockerfile              # Container configuration
├── pyproject.toml          # Dependencies and metadata
├── README.md              # Basic documentation
└── src/
    └── hud_controller/
        ├── context.py     # Persistent state management
        └── server.py      # MCP server implementation

​
Generated Files

Minimal MCP server with required tools:
from hud.server import MCPServer
from hud.server.context import attach_context

mcp = MCPServer(name="my-env")
ctx = None

@mcp.initialize
async def init(init_ctx):
    global ctx
    ctx = attach_context("/tmp/hud_ctx.sock")

@mcp.tool()
async def act() -> str:
    """Perform an action."""
    return f"Action #{ctx.act()}"

@mcp.tool()
async def setup() -> str:
    """Required for HUD environments."""
    return "Ready"

@mcp.tool()
async def evaluate() -> dict:
    """Required for HUD environments."""
    return {"count": ctx.get_count()}

if __name__ == "__main__":
    mcp.run()

​
Examples

​
Basic Usage

Create an environment in a new directory: 
hud init my-env
cd my-env

​
Current Directory

Initialize in the current directory using its name: 
mkdir awesome-tool && cd awesome-tool
hud init

​
Custom Location

Create in a specific directory: 
hud init my-env --dir ~/projects
cd ~/projects/my-env

​
Overwrite Existing

Force overwrite existing files: 
hud init my-env --force

​
Next Steps

After creating your environment:
1

Start Development

Run with hot-reload and interactive testing:
hud dev . --interactive
2

Add Your Logic

Edit src/hud_controller/server.py to add custom tools:
@mcp.tool()
async def my_custom_tool(text: str) -> str:
    """Process some text."""
    return text.upper()
3

Test Your Tools

In interactive mode, use arrow keys to select and test tools
4

Build for Production

When ready, build and share:
hud build
hud push

​
Key Concepts

​
Required Tools

Every HUD environment must implement:
  • setup() - Initialize the environment
  • evaluate() - Return environment state for evaluation

​
Context Pattern

The context pattern separates state from server logic:
  • State persists across hot-reloads
  • Server reconnects to existing context
  • Enables rapid development iteration

​
Minimal Dependencies

The template uses only essential dependencies:
  • hud[sdk] - Core HUD functionality
  • No unnecessary packages
  • Production-ready from the start

​
Tips

The generated environment is immediately runnable with hud dev. No additional setup required!
Environment names are converted to valid Docker image names automatically (underscores → hyphens).
Use --force carefully as it will overwrite existing files without confirmation.

​
See Also