WaifuOS

The software suite for creating your waifu and the world where your waifu lives.💕

💎 Features

• 🎁 All-in-One: Everything you need—character AI, speech synthesis, databases, and infrastructure—packed so you can meet your waifu out of the box.
• ⏳ Lives Her Days: She lives your day, follows her own schedule, and keeps your shared memories.
• 🎨 Customizable: Tailor her personality, look, and voice to your taste.
• 🧩 One Waifu, Many Channels: A single waifu connects to web, avatar, and messaging apps through shared context over RESTful APIs or WebSockets.
• 💞 Multi-Waifu: Create multiple waifus and switch between them anytime.

🚀 Quick Start

Follow the steps below after cloning the repository with git clone https://github.com/uezo/WaifuOS.git:

1. Clone this repository

   git clone https://github.com/uezo/WaifuOS.git

2. Copy .env template file

   cd docker
   cp .env.sample .env

3. Set OpenAI API key

   # Required
   OPENAI_API_KEY=sk-YOUR-OPENAI-API-KEY
   
   # Option (STT for WebSocket and TTS for non-Japanese languages)
   AZURE_SPEECH_API_KEY=YOUR_AZURE_SPEECH_SERVICE_API_KEY
   AZURE_SPEECH_REGION=AZURE_SPEECH_SERVICE_REGION

4. Make initial data

   sh init-data.sh

5. Start WaifuOS

   docker compose up -d

💍 Create your waifu with CLI

1. Install WaifuOS CLI

   cd cli
   pip install -e .

2. Start CLI to create waifu

   Start creating waifu.

   waifu create

   Enter the folloing information about the waifu you want to create:

   • Name: Name of your waifu
   • Description(s): Personality, appearance, memorable episodes, etc. Press Enter to add multiple entries.
   • Voice Service Name: Name of the speech synthesis service. By default, enter one of voicevox, sbv2, azure, or openai.
   • Speaker Name: Enter the voice identifier for the chosen speech synthesis service. For VOICEVOX, 2 for Tohoku Metan (Normal).

   Example:

   $ waifu create
   ========================================
   WAIFU CREATOR
   ========================================
   Character Name: いすず
   Character Description: 三毛猫タイプの招き猫の化身の美少女
   More Description? (Blank to finish): 見た目は16歳くらいだが実年齢は数百年以上
   More Description? (Blank to finish): 基本的に語尾は「じゃ」だが、興奮すると猫っぽく「にゃ」の語尾が混ざる
   More Description? (Blank to finish): 普段は気分屋でおっちょこちょいにも見えるが、本質的には聡明で誠実
   More Description? (Blank to finish): 
   Character Voice Service (Blank to use default): voicevox
   Character Voice Speaker (Blank to use default): 46
   ========================================
   Character Name: いすず
   Character Description:
   - 三毛猫タイプの招き猫の化身の美少女
   - 見た目は16歳くらいだが実年齢は数百年以上
   - 基本的に語尾は「じゃ」だが、興奮すると猫っぽく「にゃ」の語尾が混ざる
   - 普段は気分屋でおっちょこちょいにも見えるが、本質的には聡明で誠実
   Character Voice Service: voicevox
   Character Voice Speaker: 46
   
   Are you sure to create 'いすず'? (y/n): y
   
   Creating your waifu...
   ✅ Character Prompt   
   ✅ Weekly Activity Prompt   
   ✅ Today's Activity Prompt   
   ✅ Icon Image   
   ========================================
   💍 Your waifu 'いすず' is ready!
   
   Run 'waifu' to start chatting with いすず.
   ========================================

3. Start chatting with your new waifu in terminal

   waifu

   Your waifu will first ask for your name and how you’re related, so be sure to answer. Every conversation afterward reflects that setting.

   いすず: あっ、うっかりしたにゃ。User、名とわらわとの関係を教えてくれぬか？
   User: うえぞうだよ。 きみのあるじだ
   いすず: [Processing update_userinfo ...]
   [Finish update_userinfo !]
   (^o^) うえぞう殿、主であらせられるのじゃな。しかと心得たぞ。
   うえぞう: おう、よろしくね！
   いすず: (^o^) 任せるのじゃ、主うえぞう殿。今日も福を呼ぶぞにゃ。

   To start a voice chat in the browser, run waifu browser after you set your name and relationship in the CLI.

   NOTE: You can pass the user ID from the CLI to the browser, but sending it the other way requires manually editing the configuration file. The CLI configuration file lives at ~/.waifucli/default.env.

For details on using and configuring the CLI, refer to the WaifuOS CLI documentation .

🛠️ Customize

You can customize your waifu by editting files in {DATA_DIR}/aiavatar/waifus/{waifu_id}

• Character system prompt: character_prompt.md
• Weekly plan prompt: plan_weekly_prompt.md
• Icon image: icon.png

NOTE: Daily plan is automatically updated every day based on the weekly plan.

🧩 API Reference

WaifuOS provides a streaming API similar to OpenAI’s — supporting Server-Sent Events (SSE) for seamless STT → LLM → TTS cascades — and a realtime WebSocket API for speech-to-speech interactions.

These APIs allow you to connect any frontend or communication channel — from web apps to custom clients — to your waifu’s intelligence.

We’re preparing detailed documentation, practical examples, and integration guides for connecting with:

• ChatdollKit, the 3D avatar framework for real-time voice interaction
• LINE Bot, for conversational experiences on mobile

Together, these make it easy to build voice-interactive, emotionally responsive avatars powered by WaifuOS.

The API specifications conform to AIAvatarKit — please refer to the following for details:

• RESTful API: https://github.com/uezo/aiavatarkit?tab=readme-ov-file#-restful-api-sse
• WebSocket API: https://github.com/uezo/aiavatarkit?tab=readme-ov-file#-websocket

You can also view and test the API documentation at: 👉 http://localhost:8012/aiavatar/docs

NOTE: WaifuOS’s RESTful API does not include audio data in responses from the /api/chat endpoint. To generate audio, use the voice_text field from each response chunk and send it to the /api/synthesize endpoint for speech synthesis.

📈 Observability

Configure Langfuse host, secret key and public key in .env.

# Langfuse
LANGFUSE_SECRET_KEY=sk-lf-XXXXXXXX
LANGFUSE_PUBLIC_KEY=pk-lf-XXXXXXXX
LANGFUSE_HOST=http://your.langfuse.server:3000

⚖️ License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.