Skip to content

Setup

There Are 3 Ways To Run Mirumoji Locally

Pick The One That Fits You

  • GUI Setup

    Download Desktop Launcher For Your Platform To Start, Stop, and Configure Mirumoji → Easiest

  • CLI Setup

    Install With pip And Run The Docker Compose Application With mirumoji up → For Those Who Prefer The Terminal

  • Manual Setup

    Run The Docker Compose Commands Yourself, No Launcher → More Configuration

Prerequisites

Requirement Needed for Notes
Docker + Compose V2 Local Setups (GUI / CLI / Manual) Download The Cross-Platform Docker Desktop (Or Docker Engine + Compose Plugin On Linux)
Python 3.10+ CLI Setup Only To Install The mirumoji Launcher From PyPI.
NVIDIA GPU + Container Toolkit Local Transcription Backend Lets The Backend Run faster-whisper on your GPU.
A Modal Account Modal Backend Or Modal Host To Offload Transcription To Cloud GPUs, Or To Host The Whole App

Check Your Machine

With the CLI installed, run mirumoji doctor to see which dependencies you're missing

Transcription Backends

Transcription / Conversion are terribly slow for long media when running on a CPU

Mirumoji lets you choose in what GPU that work runs

  • Offloads the work to Modal cloud GPU containers

  • Your machine does not need a GPU to run this backend

  • Requires a Modal account's API Tokens → MODAL_TOKEN_ID + MODAL_TOKEN_SECRET

# CLI Configuration For Modal Transcription Backend
mirumoji config set MIRUMOJI_TRANSCRIBE_BACKEND modal
mirumoji config set MODAL_TOKEN_ID <your-token-id>
mirumoji config set MODAL_TOKEN_SECRET <your-token-secret>

  • Runs the work on your NVIDIA GPU via the Container Toolkit

  • No Cloud Account Needed

# CLI Configuration For Local Transcription Backend
mirumoji config set MIRUMOJI_TRANSCRIBE_BACKEND local
Configuration

  • The Launcher (CLI + GUI) remembers your choice in its Managed Config File, so you only need to set it once

  • Modal is the default because it works on any machine

  • See Using a GPU for a full walkthrough of both backends

LLM Features (Optional)

Provide one of these keys to unlock AI breakdowns for words and sentences + refinement for subtitles

When none are set, these features are simply disabled

# Configuring LLM Provider Keys Using The CLI
mirumoji config set OPENAI_API_KEY sk-...
mirumoji config set ANTHROPIC_API_KEY sk-ant-...
mirumoji config set GEMINI_API_KEY ...

# Any OpenAI-Compatible LLM Server Endpoint
mirumoji config set MIRUMOJI_LLM_BASE_URL https://my-endpoint/v1
mirumoji config set MIRUMOJI_LLM_API_KEY ...

Configuration Variables

See the CLI Reference for every configurable variable

Opening Mirumoji

Once the Docker Compose Application is running, the frontend is served over HTTPS

Access
  • Host Machine → https://localhost
  • Another Device On The Host's Network → https://<your-machines-IPv4-LAN-IP>

Self-Signed Certificate

  • The frontend generates a self-signed certificate for your LAN IP at startup, so your browser will show a one-time "not private" warning

  • That's expected on a local network and poses no security risk. You can safely continue past it

  • To reach Mirumoji from outside your network, see Sharing Outside Your Network

Host On Modal

Rather than running Mirumoji locally, you can deploy the whole app (server and frontend) privately to your own Modal account with one command and no local Docker, then reach it from anywhere over HTTPS

  • Modal Host Setup

    Deploy And Manage The Hosted App With mirumoji modal deploy → Access From Anywhere, No Local Docker

How It Differs From The Modal Transcription Backend