Install
Use the official installer scripts to set up MushroomAgent. Native installation is currently supported on Linux and macOS only. On Windows, use WSL2 for now.
MushroomAgent can run as a standalone agent on one machine, or as a distributed setup with one agent and one or more nodes. The agent makes decisions. Nodes collect input and execute output.
Install agent (recommended first step)
Run this command in a terminal:
curl -fsSL https://docs.kiwilightyear.com/install.sh | bash
The agent installer guides you step by step. It checks the operating system, installs required system dependencies where possible, installs uv if it is missing, downloads MushroomAgent, installs Python dependencies, links the mushroom-agent command, and runs the agent initialization wizard.
The installer is interactive. Run it from a normal terminal session, not from a fully headless shell without access to /dev/tty.
Supported systems
| System | Status | Notes |
|---|---|---|
| Linux | Supported | Debian/Ubuntu, Fedora, CentOS/RHEL, Alpine, Arch, and similar distributions are handled by the installer where possible. |
| macOS | Supported | Homebrew is used when optional system packages are needed. |
| Windows | Not native yet | Use WSL2 and run the Linux install command inside WSL. |
Agent and node roles
MushroomAgent separates the decision-making side from the device I/O side:
| Role | What it does | Typical command |
|---|---|---|
agent | The decision side. It receives context, runs the model, decides what should happen next, and sends actions back out. It can run by itself on one machine, or act like a server for remote nodes. | mushroom-agent start |
node | The device side. It collects information such as voice, video, text, and local device events, forwards that information to the agent, then executes actions returned by the agent. Actions may include voice output, screen/UI work, robot movement, or other device-specific behavior. | mushroom-agent node attach |
For a first install, use the agent installer. A standalone agent is enough for local chat and local runtime use. Use the node installer only when this machine or device should attach to an agent already running elsewhere.
During installation
Follow the prompts shown by the installer. This flow is for standalone agent setup:
- Run
install.shon the machine that will run the agent. - Enter the required model/provider configuration when the wizard asks for it.
- Let the installer finish dependency installation and initialization.
By default, files are placed under:
| Path | Purpose |
|---|---|
~/.mushroom_agent/app | MushroomAgent source checkout |
~/.mushroom_agent/config.yaml | Main configuration |
~/.mushroom_agent/skills/ | Local skills |
~/.local/bin/mushroom-agent | Command linked by the installer |
If the installer says ~/.local/bin is not in your PATH, add this to your shell config and reopen the terminal:
export PATH="$HOME/.local/bin:$PATH"
Start MushroomAgent
After installing in agent mode, start the agent with:
mushroom-agent start
This starts the agent side and local runtime on the same machine. The agent can be used by itself; a separate node is optional.
Then open the local UI in your browser:
http://127.0.0.1:7860/i/chat
Advanced install options
Most users should use the one-line command without options. If you need to customize the install, pass flags through bash -s --:
curl -fsSL https://docs.kiwilightyear.com/install.sh | bash -s -- --extras minimal
Common options for install.sh:
| Flag | Default | Description |
|---|---|---|
--dir PATH | $MUSHROOM_HOME/app | Source checkout directory |
--branch NAME | main | Git branch to install |
--extras NAME | auto prompt | Optional dependency profile (text, voice, full) |
Install node on another device
Node mode is now installed with a dedicated script. Use it only for a separate machine/device that should send collected input to an existing agent and execute actions from it. It requires an existing agent server and access key:
curl -fsSL https://docs.kiwilightyear.com/install_node.sh | bash -s -- \
--server-url ws://server-host:7860 \
--access-key <accesskey> \
--node-name "Kitchen Pi"
After installation, attach the node with:
mushroom-agent node attach
Uninstall
To clear local MushroomAgent data/config under MUSHROOM_HOME (default ~/.mushroom_agent) while keeping the directory itself, run:
curl -fsSL https://docs.kiwilightyear.com/uninstall.sh | bash
The uninstaller requires an interactive terminal and asks for a confirmation path before deleting data.
Common issues
| Symptom | Likely cause | Fix |
|---|---|---|
command not found: mushroom-agent | ~/.local/bin is not in PATH | Add export PATH="$HOME/.local/bin:$PATH" to your shell config and reopen the terminal |
| Installer says the OS is unsupported | Native install only supports Linux/macOS | Use Linux, macOS, or WSL2 on Windows |
| Installer cannot continue without a tty | The shell is fully headless | Run the command in an interactive terminal |
| Dependency install fails | Missing system package or network problem | Re-run the installer after fixing the package manager or network |
| Port 7860 is already in use | Another process is using the default port | Stop that process or change the configured server port |