Skip to main content
The hud init command scaffolds a working MCP environment using templates from the public SDK.

​
Usage

hud init [NAME] [OPTIONS]

​
Arguments

​
name
string
Environment name. If omitted, the current directory name is used.

​
Options

​
--preset
string
default:"blank"
Template preset: blank, deep-research, or browser. Short: -p
​
--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

A minimal but complete environment with controller/frontend and optional backend: 
my-env/
├── Dockerfile                # Container configuration
├── pyproject.toml            # Dependencies and metadata
├── README.md                 # Template instructions
├── tasks.json                # Example tasks
├── controller/               # MCP server (stdio)
│   ├── __init__.py           # mcp = MCPServer()
│   ├── __main__.py           # python -m controller → mcp.run()
│   ├── hooks.py              # @mcp.initialize / @mcp.shutdown
│   └── tools.py              # @mcp.tool act / setup / evaluate
└── environment/              # Backend (FastAPI example)
    └── server.py             # /health /act /reset /state

​
Dockerfile (template)

FROM python:3.11-slim
WORKDIR /app

COPY pyproject.toml ./
COPY controller/ ./controller/
COPY environment/ ./environment/
RUN pip install --no-cache-dir -e .

ENV ENV_SERVER_PORT=8005

# Start backend then launch MCP controller on stdio
CMD ["sh", "-c", "uvicorn environment.server:app --host 0.0.0.0 --port $ENV_SERVER_PORT --log-level warning & python -m controller"]
Templates may include hot-reload flags for development. Remove them for production images.

​
Examples

# Choose preset interactively (default blank)
hud init

# Create a blank template in a new directory
hud init my-env -p blank

# Browser presets
hud init my-browser -p browser

# Deep research preset (remote browser)
hud init my-deep -p deep-research

# Force overwrite
hud init my-env -p blank --force

​
Next Steps

1

Start Development

Run with hot-reload and choose your preferred UI:
# Inspector (HTTP, visual)
hud dev --inspector

# Interactive TUI (arrow keys)
hud dev --interactive
2

Edit Tools

Add tools in controller/tools.py; use @mcp.tool.
3

Build & Push

hud build
hud push

​
Presets

  • blank: Minimal controller + FastAPI backend with /health, /act, /reset, /state and example tools.
  • browser: Local browser environment preset.
  • deep-research: Remote browser environment preset (maps to remote_browser).

​
See Also