Skip to main content
This guide walks you through setting up a local Vibe Kanban Cloud instance for development and testing.

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed
  • Git to clone the repository
  • Node.js 20+ and pnpm (for running the desktop client)
  • A GitHub or Google OAuth application

​
Step 1: Clone the Repository

git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban

​
Step 2: Create OAuth Application

You need at least one OAuth provider. Choose GitHub, Google, or both.
  1. Go to GitHub Developer Settings
  2. Click New OAuth App
  3. Fill in the details:
    • Application name: Vibe Kanban Local
    • Homepage URL: http://localhost:3000
    • Authorization callback URL: http://localhost:3000/v1/oauth/github/callback
  4. Click Register application
  5. Copy the Client ID
  6. Click Generate a new client secret and copy it

​
Step 3: Configure Environment

Create a .env.remote file in the repository root: 
# Generate a secure JWT secret
openssl rand -base64 48
Copy the output and create your .env.remote:
.env.remote
# Required - JWT secret for authentication
VIBEKANBAN_REMOTE_JWT_SECRET=<paste_your_generated_secret_here>

# Optional - Password for ElectricSQL database role (electric_sync user)
ELECTRIC_ROLE_PASSWORD=

# OAuth — configure at least one provider. Leave the other empty or remove it.
GITHUB_OAUTH_CLIENT_ID=your_github_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_client_secret

# Google OAuth (leave empty if not using Google login)
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=

# Email invitations (optional — leave empty to disable)
LOOPS_EMAIL_API_KEY=
For production or self-hosting on a server, add PUBLIC_BASE_URL (your public URL, e.g. https://kanban.example.com) and REMOTE_SERVER_PORTS=0.0.0.0:3000:8081 so the server is reachable from other hosts. Defaults keep local dev unchanged.
Never commit .env.remote to version control. It’s already in .gitignore.

​
Step 4: Start the Stack

From the crates/remote directory, start all services: 
cd crates/remote
docker compose --env-file ../../.env.remote -f docker-compose.yml up --build
This starts:
  • PostgreSQL on port 5433 (external) / 5432 (internal)
  • ElectricSQL on port 3000 (internal only, used by Remote Server for real-time sync)
  • Remote Server on port 3000 (external) / 8081 (internal)
The remote server binds to 127.0.0.1:3000 only - it’s not accessible from other machines. For production, use a reverse proxy.
Wait until you see health checks passing: 
remote-server-1  | INFO remote: Server listening on 0.0.0.0:8081

​
Step 5: Access the Web Interface

Open http://localhost:3000 in your browser. You should see the Vibe Kanban Cloud login page. Sign in with your configured OAuth provider (GitHub or Google).

​
Step 6: Connect the Desktop Client (Optional)

To use the desktop client with your local server: 
# In a new terminal, from the repository root
export VK_SHARED_API_BASE=http://localhost:3000

pnpm install
pnpm run dev
The desktop client will now connect to your local Cloud instance instead of the hosted version.

​
Stopping the Stack

To stop all services: 
docker compose down
To stop and remove all data (fresh start): 
docker compose down -v

​
Troubleshooting

Ensure the database is healthy before the server starts:
# Check database status
docker compose ps

# View database logs
docker compose logs remote-db
Verify your OAuth callback URLs match exactly:
  • GitHub: http://localhost:3000/v1/oauth/github/callback
  • Google: http://localhost:3000/v1/oauth/google/callback
ElectricSQL requires the electric_sync database user, which is created automatically by the Remote Server on first startup. If ElectricSQL fails to connect:
  1. Ensure the Remote Server has started successfully and run its migrations
  2. Check that ELECTRIC_ROLE_PASSWORD is set in your .env.remote
  3. Restart the stack — ElectricSQL will retry the connection
docker compose --env-file ../../.env.remote -f docker-compose.yml restart electric
If port 3000 is in use, you can change it in docker-compose.yml:
ports:
  - "127.0.0.1:3001:8081"  # Change 3001 to your preferred port
Update your OAuth callback URLs accordingly.

​
Next Steps

Once you have local development working, you can:
  • Deploy to Fly.io for production (coming soon)
  • Deploy with Docker Compose on your own server (coming soon)