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. It prepares the environment; start the agent manually after the installer exits.
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. - Choose the dependency profile and run mode when prompted.
- 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/node.yaml | Local node identity, remote attachment, and builtin capability settings |
~/.mushroom_agent/prompts/ | Starter prompt files such as SOUL.md, AGENTS.md, and IDENTITY.md |
~/.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/web
If you only want the service/API path and browser UI without attaching the current machine as a local runtime, use:
mushroom-agent serve --ui
For local development environments where Langfuse auth is not configured, set:
export MUSHROOM_SKIP_LANGFUSE_AUTH=1
Install from source or pip
For repository development:
git clone https://github.com/kiwi-data/mushroomAgent.git
cd mushroomAgent
uv sync --extra full
source .venv/bin/activate
mushroom-agent init --run-mode text
Dependency sets for source development:
| Goal | Command |
|---|---|
| Pure text development | uv sync |
| Voice development | uv sync --extra voice |
| Full development | uv sync --extra full |
| Full runtime without dev dependencies | uv sync --no-dev --extra full |
If you only need the packaged CLI entrypoint, install:
pip install mushroom-cli
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 | Dependency profile. Accepted values include minimal, text, pure-text, none, voice, hardware, and full. minimal / text / pure-text / none install the text profile. voice / hardware install voice dependencies. |
Common environment variables:
| Variable | Purpose |
|---|---|
MUSHROOM_HOME | Data/config root; default ~/.mushroom_agent |
MUSHROOM_INSTALL_DIR | Source checkout directory; default $MUSHROOM_HOME/app |
MUSHROOM_REPO_URL | Repository URL override |
MUSHROOM_BRANCH | Git branch override |
MUSHROOM_PROXY | Optional outbound proxy |
Install node on another device
Node mode is 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.
On the agent host:
mushroom-agent accesskey create --name "Kitchen Pi" --node-id pi-kitchen
mushroom-agent serve --ui
On the node device:
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
The node installer also accepts --proxy, --dir, and --branch. You can provide MUSHROOM_SERVER_URL, MUSHROOM_ACCESS_KEY, MUSHROOM_NODE_NAME, and MUSHROOM_PROXY instead of flags.
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 |