managing-apps/docs/INSTALL_VIBE_KANBAN_AND_DEV_MANAGER.md

Installation Guide: Vibe Kanban & dev-manager-mcp

This guide will help you install and configure Vibe Kanban and dev-manager-mcp for managing your development workflow with isolated test environments.

Prerequisites

• Node.js >= 18 (or Bun)
• Docker installed and running
• PostgreSQL client (psql) installed
• Main database running on localhost:5432

Part 1: Install dev-manager-mcp

dev-manager-mcp is a daemon that manages multiple dev servers in parallel, allocating unique ports to avoid collisions.

Installation

Option 1: Use via npx (Recommended - No Installation Needed)

No installation required! Just use npx:

# Start the daemon
npx -y dev-manager-mcp daemon

Option 2: Install Globally

npm install -g dev-manager-mcp
# or
bun install -g dev-manager-mcp

Start the Daemon

Open a terminal and keep it running:

npx -y dev-manager-mcp daemon

You should see output indicating the daemon is running. Keep this terminal open.

Verify Installation

In another terminal, test the MCP connection:

# Check if daemon is accessible
npx dev-manager-mcp status

Part 2: Install Vibe Kanban

Vibe Kanban is a task management system that integrates with coding agents and can automatically start dev environments.

Installation

Option 1: Use via npx (Recommended - No Installation Needed)

# Just run it - no installation needed
npx vibe-kanban

Option 2: Install Globally

npm install -g vibe-kanban
# or
bun install -g vibe-kanban

First Run

1. Start Vibe Kanban:

npx vibe-kanban

2. Authenticate with your coding agent:

   • Vibe Kanban will prompt you to authenticate
   • Follow the instructions for your agent (Claude, Codex, etc.)

3. Access the UI:

   • Vibe Kanban will start a web server
   • Open the URL shown in the terminal (usually http://localhost:3000)

Configure MCP Integration

1. Open Vibe Kanban Settings:

   • In the Vibe Kanban UI, go to Settings
   • Find "MCP Servers" or "Agent Configuration"

2. Add dev-manager-mcp:

   {
     "mcpServers": {
       "dev-manager": {
         "command": "npx",
         "args": ["dev-manager-mcp", "stdio"]
       }
     }
   }
   

3. Configure QA Automation:

   • In Settings, find "QA" or "Testing" section
   • Enable "Auto-start dev environments"
   • Set script path: scripts/start-task-docker.sh
   • Set health check URL: http://localhost:{port}/health

Part 3: Configure for Your Project

Create Vibe Kanban Configuration

Recommended: At Projects level (to manage all projects):

Create a .vibe-kanban directory in your Projects folder:

cd /Users/oda/Desktop/Projects
mkdir -p .vibe-kanban

Create /Users/oda/Desktop/Projects/.vibe-kanban/config.json:

{
  "projectRoot": "/Users/oda/Desktop/Projects",
  "mcpServers": {
    "dev-manager": {
      "command": "npx",
      "args": ["dev-manager-mcp", "stdio"]
    }
  },
  "qa": {
    "enabled": true,
    "autoStartDevEnv": true,
    "devEnvScript": "managing-apps/scripts/start-task-docker.sh",
    "healthCheckUrl": "http://localhost:{port}/health",
    "dashboardUrl": "http://localhost:{port}"
  },
  "tasks": {
    "statuses": {
      "ready-for-qa": {
        "autoStartDevEnv": true
      }
    }
  }
}

Note: The devEnvScript path is relative to the Projects folder. For managing-apps, it's managing-apps/scripts/start-task-docker.sh. For other projects, configure project-specific scripts in Vibe Kanban's project settings.

Update Your MCP Configuration

If you're using Cursor or another editor with MCP support, add to your MCP config (usually ~/.cursor/mcp.json or similar):

{
  "mcpServers": {
    "dev-manager": {
      "command": "npx",
      "args": ["dev-manager-mcp", "stdio"]
    }
  }
}

Part 4: Usage Workflow

For Development (Agent)

1. Make code changes
2. Start test environment:

   cd /Users/oda/Desktop/Projects/managing-apps
   bash scripts/start-dev-env.sh DEV-A3X9
   

3. Test your changes at the provided URLs
4. Stop when done:

   bash scripts/stop-task-docker.sh DEV-A3X9
   

For QA (Vibe Kanban)

1. Move task to "Ready for QA" status
2. Vibe Kanban automatically:
   • Starts a Docker environment
   • Copies the database
   • Provides test URLs
3. Test the task
4. Move to "Done" or "Needs Changes"
5. Vibe Kanban automatically stops the environment

Manual Management

Start an environment:

cd /Users/oda/Desktop/Projects/managing-apps
bash scripts/start-task-docker.sh TASK-123 0

Check status:

npx dev-manager-mcp status

View logs:

docker logs managing-api-TASK-123

Stop an environment:

bash scripts/stop-task-docker.sh TASK-123

Troubleshooting

dev-manager-mcp Issues

Daemon not starting:

• Check Node.js version: node --version (needs >= 18)
• Try: npx -y dev-manager-mcp daemon --verbose

Cannot connect to daemon:

• Make sure daemon is running in another terminal
• Check if port is already in use
• Restart the daemon

Vibe Kanban Issues

Cannot start:

• Check Node.js version: node --version (needs >= 18)
• Try: npx vibe-kanban --verbose

MCP not working:

• Verify dev-manager-mcp daemon is running
• Check MCP configuration in Vibe Kanban settings
• Restart Vibe Kanban

Auto-start not working:

• Check script path in configuration
• Verify script is executable: chmod +x scripts/start-task-docker.sh
• Check Vibe Kanban logs

Docker Issues

Port conflicts:

• Use different port offset: bash scripts/start-task-docker.sh TASK-123 10
• Check what's using ports: lsof -i :5000

Database copy fails:

• Verify main database is running: docker ps | grep postgres
• Check PostgreSQL client: which psql
• Verify connection: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d managing -c '\q'

Next Steps

1. ✅ Install dev-manager-mcp (via npx)
2. ✅ Install Vibe Kanban (via npx)
3. ✅ Start dev-manager-mcp daemon
4. ✅ Start Vibe Kanban
5. ✅ Configure MCP integration
6. ✅ Test with a sample task

Resources

• Vibe Kanban GitHub
• Vibe Kanban Documentation
• dev-manager-mcp GitHub
• MCP Documentation

Support

• Vibe Kanban: GitHub Discussions
• dev-manager-mcp: GitHub Issues