Skip to main content

Local Development

These are the things that matter when running MushroomAgent locally, regardless of platform.

Baseline checklist​

# 1. Check Python version
python3 --version          # must be 3.11+

# 2. Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Clone and sync
git clone <repo-url>
cd MushroomAgent
uv sync
source .venv/bin/activate

# 4. Initialize config
mushroom-agent init

# 5. Set your API key in ~/.mushroom_agent/config.yaml
#    llm.api_key: "sk-..."

# 6. Start the agent
MUSHROOM_SKIP_LANGFUSE_AUTH=1 mushroom-agent serve --ui

# 7. Open http://127.0.0.1:7860/i/chat

Common per-platform issues​

Linux​

  • Port in use: If port 7860 is taken, use --port 9000
  • Missing dev libraries: uv sync may need python3-dev or build-essential
  • File permissions: Ensure ~/.mushroom_agent/ is writable

macOS​

  • Old system Python: macOS bundles Python 3.9. Install 3.12+ via brew install python@3.12
  • SSL certificates: If you get SSL errors, run /Applications/Python\ 3.12/Install\ Certificates.command
  • Path issues: brew Python may be at /opt/homebrew/bin/python3

Windows (native)​

  • Path separator: Use forward slashes or escaped backslashes in config
  • No ~ expansion: Use absolute paths like C:\Users\you\.mushroom_agent
  • Shell: Use PowerShell or Git Bash, avoid cmd.exe for uv
  • Symlinks: Some Python packages need symlink support; enable Developer Mode in Windows settings

Verify it works​

After starting, the chat page at http://127.0.0.1:7860/i/chat should load. Send "hello" — you should get a response within a few seconds. If not, check:

  • llm.api_key is a valid key in config.yaml
  • llm.base_url is correct for your provider
  • No firewall blocking port 7860