Installation Guide

Get Rimuru running on your machine in under a minute. Choose the method that suits your workflow — npm global install, an alternative package manager, Docker, or building from source.

Prerequisites

Before installing, make sure your environment meets these requirements:

  • Node.js 18+ (LTS recommended) — Rimuru runs on top of Node.js and uses modern APIs not available in earlier versions.
  • npm, yarn, or pnpm — Any of the major package managers works. npm ships with Node.js by default.
  • Git (optional) — Required only if you plan to install Rimuru directly from source.

Quick Install (npm)

The fastest way to install Rimuru is via npm. Open a terminal and run:

npm install -g rimuru

The -g flag installs Rimuru globally so the rimuru command is available anywhere on your system.

Verify the installation succeeded:

rimuru --version rimuru --help

If you see the version number and help output, you're ready to go. Head over to the Quick Start guide to create your first project.

Alternative: Global via yarn / pnpm

If you use yarn or pnpm as your primary package manager, the global install commands are just as simple:

yarn global add rimuru
pnpm add -g rimuru

Both commands install Rimuru globally and register the rimuru binary. After installation, verify with rimuru --version.

Installing a Specific Version

By default npm installs the latest stable release. You can pin a specific version, a pre-release channel, or an exact tag:

npm install -g rimuru@latest
npm install -g rimuru@beta
npm install -g rimuru@1.0.0

Use @latest for the most recent stable release, @beta for cutting-edge features that are still undergoing testing, and an exact semver string when you need to lock to a specific version for compatibility.

Platform Support

Rimuru is cross-platform and actively tested on the following operating systems and architectures:

  • Linux (x64, arm64) — fully supported. Rimuru is built and tested on modern Linux kernels (5.x+). The primary development target.
  • macOS (Intel, Apple Silicon) — fully supported. Both Intel and Apple Silicon (M1, M2, M3, M4) are tested every release.
  • Windows (x64) — via WSL2 recommended. Native Windows support is currently in beta. If you encounter issues on Windows, please report them on GitHub.

Shell Completions

Rimuru ships with built-in shell completion generation. Set up tab-completion for your preferred shell:

Bash

rimuru completion bash > /etc/bash_completion.d/rimuru

After running the command, restart your terminal or source the file with source /etc/bash_completion.d/rimuru.

Zsh

rimuru completion zsh > /usr/local/share/zsh/site-functions/_rimuru

Ensure the target directory is in your fpath. Add fpath=(/usr/local/share/zsh/site-functions $fpath) to your .zshrc if needed, then restart your shell.

Fish

rimuru completion fish > ~/.config/fish/completions/rimuru.fish

Fish automatically loads completions from ~/.config/fish/completions/, so no additional configuration is required.

Docker (Optional)

A Docker image is available for containerized environments. Create aDockerfile in your project:

FROM node:20-slim RUN npm install -g rimuru ENTRYPOINT ["rimuru"]

Build and run the image:

docker build -t rimuru . docker run -it rimuru --help

The image uses node:20-slim as its base to keep the footprint small. You can mount your project directory as a volume when running workflows:

docker run -it -v "$(pwd):/workspace" rimuru init

Setting Up Your First Project

Once Rimuru is installed, scaffold a new project with the built-in init command:

mkdir my-rimuru-project && cd my-rimuru-project rimuru init

Running rimuru init creates the following structure:

  • rimuru.yaml — Main configuration file that defines your project settings, agents, MCP servers, and plugins.
  • .rimuru/ — Rimuru working directory. Contains runtime state, logs, and cached data. This directory should be added to .gitignore.
  • agents/ — Agent configuration directory. Each file in this directory defines a specialized agent with its own model, temperature, and tool configuration.
  • workflows/ — Workflow definitions. YAML files that describe multi-step agent pipelines. Use the visual builder or write them by hand.

Configuration (rimuru.yaml)

The rimuru.yaml file is the heart of your project. Here's a minimal working example:

project:
  name: my-project
  version: 1.0.0

agents:
  default:
    model: deepseek-v4-flash-free
    temperature: 0.2

mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem"]

plugins:
  - rimuru-plugin-docs
  - rimuru-plugin-testing

The project section sets metadata. The agents section defines one or more agents — each with its own model and generation parameters. The mcp_servers section registers MCP (Model Context Protocol) servers that provide tools and resources to your agents. plugins extends Rimuru with additional capabilities from the ecosystem.

See the CLI documentation for a full reference of all configuration options.

Uninstalling

To completely remove Rimuru from your system:

npm uninstall -g rimuru

This removes the rimuru binary. Your project files and global configuration data are preserved so you can reinstall later without losing your setup.

To also remove all configuration and data (projects, logs, cached models):

rm -rf ~/.rimuru

Note: This is irreversible. Back up any important configuration before deleting the ~/.rimuru directory.

Troubleshooting

If something doesn't work after installation, check these common issues:

“Command not found”

This usually means the npm global bin directory isn't in yourPATH. Run npm bin -g to find the global bin path and add it to your shell profile:

export PATH="$(npm bin -g):$PATH"

Add the line above to your ~/.bashrc, ~/.zshrc, or equivalent shell config file.

Permission errors

On Unix-like systems, global npm installs may require elevated permissions. Use sudo to work around it:

sudo npm install -g rimuru

Alternatively, configure npm to use a prefix you own. Create a directory for global packages and point npm to it:

mkdir ~/.npm-global npm config set prefix ~/.npm-global

Then add ~/.npm-global/bin to your PATH.

Node version too old

Rimuru requires Node.js 18 or later. Check your current version:

node --version

If it's below 18, update Node.js using your package manager,nodejs.org, or a version manager like nvm.

Network errors

If npm fails to download packages, check your internet connection and proxy settings. You can force a specific registry:

npm install -g rimuru --registry=https://registry.npmjs.org

If the issue persists, it may be a temporary outage on npm's side — wait a few minutes and try again.