Skip to main content

Getting Started

Get MushroomAgent up and running on your machine in a few minutes. This guide walks through the shortest supported path from install to a working local agent, then shows when to use server-only and node mode.

For a first setup, install MushroomAgent as an agent. The agent is the decision side: it receives information, calls the model, decides what action should happen, and can run by itself on one machine. A node is only needed when another device should collect input or execute output for an agent running elsewhere.

What you need​

  • Linux or macOS. On Windows, use WSL2 for now.
  • A normal interactive terminal
  • A working LLM API key

Install an agent first​

Start by getting an agent configured locally. Choose one of these two paths:

  • Quick install: fastest way for most users.
  • Developer mode: install from source for local development.

Once either path is complete, start the agent with mushroom-agent start for a full local runtime, or mushroom-agent serve --ui when you only want the service and browser UI.

Quick install​

  1. Run the installer

    curl -fsSL https://docs.kiwilightyear.com/install.sh | bash

    The installer checks your system, installs missing dependencies where possible, downloads MushroomAgent, links the mushroom-agent command, installs Python dependencies, and runs the initialization wizard. It prepares the environment; it does not keep an agent service running after installation.

  2. Follow the prompts

    Choose the default agent mode for a local setup. For text chat, choose Pure text mode and enter the provider, model, and API key when the wizard asks for them.

  3. Start the agent

    mushroom-agent start

    Open http://127.0.0.1:7860/web in your browser.

For non-interactive dependency selection, pass an extras profile:

curl -fsSL https://docs.kiwilightyear.com/install.sh | bash -s -- --extras minimal
curl -fsSL https://docs.kiwilightyear.com/install.sh | bash -s -- --extras voice

Developer mode​

If you want to develop from source code instead of using the one-line installer, use this flow:

  1. Clone the source repository

    git clone https://github.com/kiwi-data/mushroomAgent.git
    cd mushroomAgent

  2. Install dependencies for full local development

    uv sync --extra full
    source .venv/bin/activate
    which mushroom-agent

    Confirm one of the returned paths is .venv/bin/mushroom-agent before running mushroom-agent commands.

  3. Initialize local config

    mushroom-agent init --run-mode text

    The wizard writes ~/.mushroom_agent/config.yaml, ~/.mushroom_agent/node.yaml, local prompt files, and a local secrets sidecar. Re-run with --force only when you intentionally want to overwrite generated files.

  4. Start local environment

    mushroom-agent start

    Open http://127.0.0.1:7860/web in your browser.

Node mode​

Node mode is for a separate device that should collect input and execute output for an agent running elsewhere. It is not required for normal local chat.

You can set up node mode after completing either agent installation path above and creating an access key for the device.

A node collects information such as voice, video, text, and local device events, then forwards it to the agent. The agent decides what to do and sends actions back to the node. Those actions may be voice output, UI actions, robot movement, or other device-specific behavior.

On the agent host, create an access key and start the service:

mushroom-agent accesskey create --name "Kitchen Pi" --node-id pi-kitchen
mushroom-agent serve --ui

Then run the dedicated node installer on the 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"

Then start the node with:

mushroom-agent node attach

Voice mode​

Voice-related configuration can be generated directly by the installer wizard. Choose voice mode when prompted, or initialize explicitly from a source checkout:

mushroom-agent init --run-mode voice

Then start as usual:

mushroom-agent start

Voice mode may require extra system packages and the voice or full dependency profile.

If start fails​

If mushroom-agent start fails because local auth integration is not configured, disable Langfuse auth for local testing and retry:

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent start

If generated config files are stale and you want to recreate them, re-initialize local config:

mushroom-agent init --force
mushroom-agent start

What to do next​

Docs hubs

Browse the full documentation by topic.

CLI Reference

Learn about remote mode and multi-device setups.