Platforms

MushroomAgent runs on Linux, macOS, and Windows. Since it is a Python project, the core requirements are the same across platforms.

Supported platforms

Platform	Status	Notes
Linux	Supported	Native. Use systemd for long-running serve instances.
macOS	Supported	Native. Use brew for Python if needed.
Windows	Supported	WSL recommended for best experience. Native Python works with path adjustments.

Cross-platform checklist

Regardless of your platform, make sure:

1. Python 3.11+ — check with python3 --version
2. uv or pip — uv is strongly recommended
3. uv sync has been run and .venv is activated
4. mushroom-agent init has created ~/.mushroom_agent/
5. llm.api_key is set in config.yaml
6. The browser can reach http://127.0.0.1:7860/i/chat

Platform notes

Linux

Everything works out of the box. For running mushroom-agent serve as a persistent service, use systemd:

[Unit]
Description=MushroomAgent
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/MushroomAgent
ExecStart=/path/to/MushroomAgent/.venv/bin/mushroom-agent serve
Restart=on-failure

[Install]
WantedBy=multi-user.target

macOS

Install Python via Homebrew if the system Python is too old:

brew install python@3.12

For long-running serve, use launchd or tmux/screen.

Windows

WSL2 is the recommended way. Install WSL2 and use the Linux instructions above.

If using native Windows:

• Install Python from python.org
• Use absolute paths in config.yaml (no ~ expansion)
• The virtual environment activation is .venv\Scripts\activate

Local development

Baseline checklist and per-platform detail.