Installation

Detailed installation and configuration guide for Kuroryuu.

System Requirements

| Component | Minimum | Recommended | |-----------|---------|-------------| | OS | Windows 10 | Windows 11 | | Python | 3.12 | 3.12+ | | Node.js | 18.x | 22.x | | RAM | 8 GB | 16 GB+ | | Disk | 1 GB | 2 GB |

Python 3.12 is required — MCP Core uses FastAPI features not available in older versions.

Windows Installation (Native)

Step 1: Clone the Repository

git clone https://github.com/ahostbr/kuroryuu-public.git
cd kuroryuu-public

Step 2: Run the Setup Script

.\setup-project.ps1

This 12-step script handles the entire setup:

Sets KURORYUU_PROJECT_ROOT — Persistent environment variable pointing to the project root
Creates runtime directories — ai/checkpoints/, ai/logs/, ai/inbox/, ai/rag_index/, and more
Generates .mcp.json — From template with resolved paths for your machine
Generates config files — Claude Code settings and task tracking from templates
Creates Python 3.12 venv — Isolated .venv_mcp312 environment
Installs Python deps — MCP Core, Gateway, MCP Stdio, speech/audio (edge-tts, pyaudio)
Installs Node.js deps — Desktop, PTY Daemon, Web UI, Tray Companion
Runs npm audit fix — Patches known vulnerabilities
Installs Playwright CLI — Browser automation skills
Copies build assets — Desktop app icons from resources/ to build/
Builds Electron apps — Desktop app and Tray Companion
Downloads FFmpeg — ~80MB GPL build for screen capture

Optional flags:

.\setup-project.ps1 -SkipPython   # Skip Python venv and deps
.\setup-project.ps1 -SkipNode     # Skip Node.js deps
.\setup-project.ps1 -Force        # Overwrite existing configs

Step 3: Restart Terminal

After setup completes, restart your terminal to pick up the new KURORYUU_PROJECT_ROOT environment variable.

Step 4: Start All Services

.\run_all.ps1

This starts the Gateway, MCP Core, and Desktop app together.

To stop everything:

.\kill_all.ps1

To start services individually:

cd apps/gateway && python server.py        # Gateway (port 8200)
cd apps/mcp_core && python server.py       # MCP Core (port 8100)
cd apps/desktop && npm run dev             # Desktop App (dev mode)

Docker Installation (Cross-Platform)

Docker support is for backend developers and CI pipelines. Kuroryuu is Windows-first; full functionality requires native installation.

Setup

git clone https://github.com/ahostbr/kuroryuu-public.git
cd kuroryuu-public
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY (required for chat)
docker-compose up -d

Services

| Service | Port | Health Endpoint | Purpose | |---------|------|-----------------|---------| | MCP Core | 8100 | /health | MCP tool server (15 tools, 107 actions) | | Gateway | 8200 | /v1/health | FastAPI + WebSocket, chat streaming | | PTY Daemon | 7072/7073 | /health | Terminal emulation backend | | Web UI | 3000 | / | React SPA served via nginx |

Environment Variables

# Required for chat functionality
ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional overrides
KURORYUU_GATEWAY_PORT=8200
KURORYUU_MCP_PORT=8100
KURORYUU_AUTH_ENABLED=true
KURORYUU_AUTH_PASSWORD_HASH=<sha256-hash>

Docker Commands

docker-compose up -d          # Start in background
docker-compose logs -f         # Follow all logs
docker-compose logs -f gateway # Follow specific service
docker-compose build && docker-compose up -d  # Rebuild
docker-compose down            # Stop all
docker-compose down -v         # Stop and remove volumes

Limitations in Docker

Windows-only features are automatically disabled:

k_capture — Requires Win32 display APIs
k_pccontrol — Requires PowerShell + Win32 APIs
Desktop Electron app — Use Web UI instead
Tray Companion — Windows SAPI required

Configuration

MCP Server Integration

The setup script generates .mcp.json automatically. To manually configure Claude Code, add to your settings:

{
  "mcpServers": {
    "kuroryuu": {
      "type": "sse",
      "url": "http://127.0.0.1:8200/v1/mcp/sse"
    }
  }
}

Claude Code Integration

Kuroryuu monitors Claude Code teams via file watchers:

~/.claude/teams/ — Team configurations
~/.claude/tasks/ — Task data

No additional configuration needed — Kuroryuu detects Claude Code teams automatically.

Troubleshooting

Setup script fails — Python 3.12 not found

# Verify Python 3.12 is installed with the py launcher
py -3.12 --version   # Should show Python 3.12.x

Install from python.org — ensure the py launcher checkbox is selected during install.

Gateway won't start

# Check if port 8200 is in use
netstat -an | findstr 8200

# Kill everything and restart
.\kill_all.ps1
.\run_all.ps1

Desktop app won't build — missing icon

The desktop app requires apps/desktop/build/icon.png (256x256 PNG). The setup script copies this from apps/desktop/resources/ automatically. If it's missing:

copy apps\desktop\resources\Kuroryuu_png.png apps\desktop\build\icon.png

MCP tools not responding

# Check MCP Core health
curl http://127.0.0.1:8100/health

# Verify tools list
curl -X POST http://127.0.0.1:8100/mcp -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Desktop app blank terminals

Restart the app — terminals persist via the PTY daemon and survive restarts. Check ai/logs/main.log for errors.

TTS not working

Check that TTS hooks are configured in ~/.claude/settings.json. The desktop app can sync these automatically via Settings > TTS.