Related Pages

Related topics: Key Concepts, Development Setup

Project Introduction

Vibe Kanban is a specialized project planning and agent execution platform designed for software engineering teams that leverage AI coding agents. The project provides an integrated environment where teams can plan work using kanban issues and execute coding tasks through dedicated workspaces that give AI agents controlled access to code branches, terminals, and development servers.

Purpose and Scope

The primary purpose of Vibe Kanban is to address the workflow inefficiency that emerges when software engineers spend significant time planning and reviewing AI coding agent activities. By providing a structured kanban interface combined with agent execution capabilities, the platform enables teams to:

• Plan and prioritize work through visual kanban boards
• Execute coding tasks through multiple supported AI agents
• Review AI-generated changes with inline commenting capabilities
• Preview applications directly within the development environment
• Create and merge pull requests without context switching

Sources: README.md

Supported AI Agents

Vibe Kanban integrates with a wide variety of coding agents, allowing teams to choose the most appropriate tool for their needs. The platform supports the following agents:

Sources: README.md

Architecture Overview

Vibe Kanban follows a monorepo architecture with multiple packages organized for different concerns.

graph TD
    subgraph "packages/"
        WC["web-core<br/>(packages/web-core)"]
        UI["ui<br/>(packages/ui)"]
        REM["remote-web<br/>(packages/remote-web)"]
    end
    
    subgraph "crates/"
        SERVER["server<br/>(crates/server)"]
    end
    
    WC <--> SERVER
    UI <--> WC
    REM --> SERVER

Core Packages

The web application is built using multiple TypeScript packages:

• packages/web-core: Contains shared hooks, stores, dialogs, and components that form the business logic layer
• packages/ui: Reusable UI components including CommandBar, WorkspaceSidebar, and various input components
• packages/remote-web: Pages and layouts for the remote/web deployment scenarios

The backend is implemented in Rust using Actix-web, providing OAuth authentication and API endpoints.

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts

Key Features

Kanban Issue Management

The kanban board provides a visual interface for creating, prioritizing, and assigning issues. Teams can organize work privately or collaboratively, with issues flowing through customizable status columns.

Workspace Execution

Workspaces provide isolated environments for AI agents to execute tasks. Each workspace includes:

• A dedicated git branch for the task
• Terminal access for command execution
• Integrated dev server for live preview
• Diff viewing and inline commenting

graph LR
    A[Kanban Issue] --> B[Create Workspace]
    B --> C[Agent Executes on Branch]
    C --> D[Review Diffs]
    D --> E[Inline Comments]
    E --> F[Create PR]
    F --> G[Merge]

Sources: packages/ui/src/components/WorkspacesSidebar.tsx

Command Bar Navigation

The application features a comprehensive command palette (activated via Cmd+K) that provides quick access to all major functionality:

• Repository and branch selection
• Status and priority filtering
• Issue navigation and creation
• Workspace management

// Keyboard shortcut mappings from useWorkspaceShortcuts.ts
const SHORTCUTS = {
  'v>p': 'Toggle Preview Mode',
  'v>s': 'Toggle Left Sidebar', 
  'v>h': 'Toggle Left Main Panel',
  'x>p': 'Git Create PR',
  'x>m': 'Git Merge',
  'x>r': 'Git Rebase',
  'x>u': 'Git Push',
  't>d': 'Toggle Dev Server',
  'r>s': 'Run Setup Script',
  'r>c': 'Run Cleanup Script'
};

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts

Attachment and Comment System

Issues support rich commenting with file attachments. The system handles upload progression, confirmation states, and attachment metadata tracking.

// Attachment state transitions
type AttachmentStatus = 'uploading' | 'confirming' | 'completed';

interface LocalAttachmentMetadata {
  path: string;
  pending_status: AttachmentStatus;
  upload_progress: number;
}

Sources: packages/web-core/src/shared/hooks/useAzureAttachments.ts

Pending Approval Workflow

When agents require human authorization for sensitive operations, the system displays a pending approval entry that allows users to approve or deny requests with explanatory messages.

stateDiagram-v2
    [*] --> AgentRequestsAction
    AgentRequestsAction --> PendingApproval
    PendingApproval --> Approved: User Approves
    PendingApproval --> Denied: User Denies
    Approved --> [*]
    Denied --> AgentResubmits: Agent Adjusts
    AgentResubmits --> PendingApproval

Sources: packages/web-core/src/shared/components/NormalizedConversation/PendingApprovalEntry.tsx

UI State Management

The application maintains comprehensive UI state through Zustand stores, handling layout modes, panel visibility, and workspace-specific configurations.

// Core UI preferences from useUiPreferencesStore.ts
interface UiPreferencesState {
  layoutMode: 'workspaces' | 'kanban' | 'accordion';
  isLeftSidebarVisible: boolean;
  isRightSidebarVisible: boolean;
  isTerminalVisible: boolean;
  paneSizes: Record<string, number>;
  workspacePanelStates: Record<string, WorkspacePanelState>;
}

Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts

OAuth Authentication

The server implements OAuth authentication flows for secure user sessions, returning HTML responses for browser-based authentication callbacks.

// Simplified OAuth response structure
struct OAuthCallback {
    message: String,     // Success or error message
    app_icon: Vec<u8>,    // Base64 encoded application icon
}

Sources: crates/server/src/routes/oauth.rs

Git Operations

The platform integrates comprehensive Git functionality directly into the workspace workflow:

Force push operations require explicit user confirmation through a dedicated dialog due to the destructive nature of the operation.

Sources: packages/web-core/src/shared/dialogs/command-bar/ForcePushDialog.tsx

Conflict Resolution

When Git operations encounter conflicts, the application provides a dedicated dialog to help users resolve them, displaying conflicted files and offering options to create new sessions or continue with existing ones.

interface ResolveConflictsDialogProps {
  conflictedFiles: string[];
  profiles?: ExecutorProfile[];
  hasExistingSession: boolean;
  createNewSession: boolean;
  onCreateNewSessionChange: (value: boolean) => void;
}

Sources: packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx

Development Workflow Summary

graph TD
    A[Plan Issue on Kanban] --> B[Create Workspace]
    B --> C[Select Agent]
    C --> D[Agent Executes Tasks]
    D --> E{Requires Approval?}
    E -->|Yes| F[User Reviews & Approves/Denies]
    F --> G[Agent Continues]
    E -->|No| G
    G --> H[Review Diffs & Comments]
    H --> I[Create Pull Request]
    I --> J[Merge to Main]
    J --> K[Archive Workspace]

The platform streamlines the entire development lifecycle from initial planning through final merge, keeping all stakeholders in a single interface throughout the process.

Related Pages

Related topics: Project Introduction, Database and Data Models

Key Concepts

Vibe Kanban is a development workflow management tool designed for software engineering teams that work with AI coding agents. The application combines kanban-based issue planning with workspace-based agent execution, enabling engineers to plan, delegate, and review AI-assisted coding work within a unified interface.

Core Architecture Overview

The system is built around several interconnected concepts that work together to manage the lifecycle of AI-assisted development tasks.

graph TD
    A[Organizations] --> B[Projects]
    B --> C[Kanban Issues]
    B --> D[Workspaces]
    C -->|Assign to| D
    D --> E[Sessions]
    D --> F[Scratches]
    E --> G[Processes]
    G --> H[Git Operations]
    E --> I[Attachments]
    D --> J[Dev Server]

Projects

Projects serve as the top-level organizational unit in Vibe Kanban. Each project contains its own kanban board and associated workspaces.

Project Properties

Projects are organized under organizations and contain all related kanban issues and workspaces. Sources: packages/remote-web/src/pages/HomePage.tsx:60-80

Project Card Component

The ProjectCard component renders project items in the home page grid layout, displaying project name and providing navigation to individual project views. Sources: packages/remote-web/src/pages/HomePage.tsx:80-100

Workspaces

Workspaces are the execution environment where coding agents operate. Each workspace provides an isolated branch, terminal access, and a dev server for a single coding agent.

Workspace Lifecycle

stateDiagram-v2
    [*] --> Active: Created
    Active --> Running: Agent starts
    Running --> Active: Agent pauses
    Active --> Archived: User archives
    Running --> Completed: Task finished
    Archived --> Active: User restores
    Completed --> [*]
    Active --> [*]

Workspace Properties

Sources: packages/ui/src/components/WorkspacesSidebar.tsx:20-40

Workspace Panel State Management

The UI preferences store manages workspace panel visibility states, allowing users to toggle the left main panel and persist these preferences. Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts:30-50

Sessions

Sessions represent individual agent execution instances within a workspace. Each time a coding agent runs, it creates a new session that captures the execution context.

Session Attributes

Sessions track the complete execution context including:

• Profile Configuration: The AI model and agent settings used
• Context Window: Available memory and context for the agent
• Execution History: Commands executed and outputs generated
• Process Chain: Sequential processes that ran during the session

Sources: packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:20-60

Process Tracking

Each session contains multiple processes that represent discrete units of work:

graph LR
    A[Process Start] --> B[Running]
    B --> C[User Approval Point]
    C -->|Approved| B
    C -->|Rejected| D[Stopped]
    B --> E[Completed]
    D --> E

The process tab displays:

• Process status (running, completed, stopped)
• Started timestamp
• Completed timestamp
• Copy logs functionality

Sources: packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:60-100

Kanban Issues

Kanban issues are the planning units in Vibe Kanban. They can be created, prioritized, and assigned to workspaces for execution.

Issue Comments

The IssueCommentsSection component handles all comment-related functionality for issues:

interface IssueCommentsSectionProps {
  comments: IssueCommentData[];
  commentInput: string;
  editingCommentId: string | null;
  editingValue: string;
  reactionsByCommentId: Map<string, ReactionGroup[]>;
  localAttachments?: LocalAttachmentMetadata[];
  // ... additional handlers
}

Sources: packages/ui/src/components/IssueCommentsSection.tsx:1-30

Comment Features

Issue Priority and Status

Issues support priority levels and status tracking, accessible through the command bar. Priority labels include urgency indicators, while status values track issue progression through workflow states. Sources: packages/ui/src/components/CommandBar.tsx:80-100

Scratches

Scratches are temporary execution spaces that allow quick experimentation or notes without creating a full workspace. They share the workspace execution environment but are not persisted in the same way.

Git Operations

Vibe Kanban integrates Git operations directly into the workspace workflow:

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts:1-20

Conflict Resolution

When conflicts occur during Git operations, the ResolveConflictsDialog handles conflict detection and resolution workflows, allowing users to select agents and profiles for creating new resolution sessions. Sources: packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:50-80

UI Layout and Navigation

Layout Modes

Vibe Kanban supports two primary layout modes:

The layout mode can be toggled via the UI preferences store. Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts:20-30

Keyboard Shortcuts

Comprehensive keyboard shortcuts enable efficient workflow management:

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts:1-30

Sidebar Components

The WorkspacesSidebar provides the main navigation interface with sections for:

• Active workspaces
• Draft workspaces (in creation)
• Archived workspaces
• Needs attention section (with raised hand indicator)

Workspaces can be filtered and sorted, with visual indicators for running agents, pending approvals, and unseen activity. Sources: packages/ui/src/components/WorkspacesSidebar.tsx:10-50

Command Bar

The command bar (CommandBar) provides quick access to all application actions through a searchable interface:

Command Item Types

Sources: packages/ui/src/components/CommandBar.tsx:100-130

Workspace Selection

The WorkspaceSelectionDialog enables linking kanban issues to workspaces, displaying available workspaces with their branch information and archive status. Sources: packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:30-60

Data Flow Architecture

graph TD
    subgraph Frontend
        A[React Components] --> B[Zustand Stores]
        B --> C[API Client]
    end
    
    subgraph Backend
        C --> D[Rust Server]
        D --> E[Database]
        D --> F[OAuth Handler]
    end
    
    B -->|Optimistic Updates| A
    C -->|REST API| D
    D -->|CRUD| E

File Tree Persistence

The UI preferences store persists file tree collapsed paths per workspace using a keyed storage system:

const key = workspaceId ? `file-tree:${workspaceId}` : '';
const paths = useUiPreferencesStore((s) => s.collapsedPaths[key] ?? []);

This ensures that file tree expansion states are preserved across sessions and workspace switches. Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts:70-100

Integration Points

OAuth Flow

The Rust server handles OAuth authentication flows, returning branded HTML pages for authentication completion. Sources: crates/server/src/routes/oauth.rs:1-30

GitHub CLI Setup

The GhCliSetupDialog guides users through GitHub CLI installation and authentication, with help instructions for common error variants. Sources: packages/web-core/src/shared/dialogs/auth/GhCliSetupDialog.tsx:1-50

Related Documentation

• Installation Guide
• Getting Started
• API Reference
• Configuration

Related Pages

Related topics: Project Introduction, Backend Architecture

Development Setup

This guide covers the development environment setup for Vibe Kanban, a visual project management tool for developers that integrates with git repositories and coding agents.

Project Architecture Overview

Vibe Kanban is a monorepo application built with multiple technologies:

graph TD
    subgraph "Frontend (TypeScript/React)"
        A[packages/web-core] --> B[packages/ui]
        A --> C[packages/remote-web]
    end
    
    subgraph "CLI Layer"
        D[npx-cli] --> A
        D --> E[vibe-kanban-mcp]
    end
    
    subgraph "Backend (Rust)"
        F[crates/server]
    end
    
    D --> F

Prerequisites

System Requirements

Required Tools

1. Coding Agent Authentication - Configure authentication for your preferred coding agent (Claude Code, Codex, Gemini CLI, etc.)
2. Git - Repository operations and worktree management
3. Azure CLI (optional) - For attachment upload functionality

Repository Structure

vibe-kanban/
├── packages/
│   ├── web-core/          # Core React hooks, stores, and components
│   ├── ui/                # Shared UI components
│   ├── remote-web/        # Web application pages
│   └── public/            # Static assets
├── crates/
│   └── server/            # Rust backend server
├── npx-cli/               # CLI entry point
└── scripts/               # Build and development scripts

Sources: npx-cli/README.md:1-20

Installation

1. Clone the Repository

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

2. Install Dependencies

npm install -g pnpm
pnpm install

3. Build the CLI

cd npx-cli
pnpm build

The build script uses esbuild to bundle the TypeScript source:

// npx-cli/package.json
{
  "scripts": {
    "build": "esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=bin/cli.js"
  }
}

Sources: npx-cli/package.json:8

Development Workflow

Running the Application

npx vibe-kanban

This launches the application locally and opens it in your browser automatically.

Available CLI Commands

npx vibe-kanban --help
npx vibe-kanban --version
npx vibe-kanban review --help
npx vibe-kanban mcp --help

Sources: npx-cli/README.md:12-17

Hotkeys Reference

The application provides keyboard shortcuts for common actions:

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts

State Management

The application uses Zustand stores for state management:

graph TD
    A[UI Store] -->|paneSizes, collapsedPaths| B[useUiPreferencesStore]
    C[Workspace Store] -->|diff data| D[useWorkspaceDiffStore]
    E[Project Store] -->|organizations, projects| F[Remote Data]

Key Stores

Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts

Attachment Handling

File attachments use Azure Blob Storage for uploads:

sequenceDiagram
    participant User
    participant UI as React Components
    participant API as confirmAttachmentUpload
    participant Azure as Azure Blob Storage
    
    User->>UI: Select file
    UI->>Azure: Upload file chunk
    Azure-->>UI: Upload progress (0-100%)
    UI->>API: Confirm upload
    API-->>UI: Return attachment ID

The attachment confirmation payload includes:

{
  project_id: string,
  upload_id: string,
  filename: string,
  content_type: string,
  size_bytes: number,
  hash: string,
  issue_id: string,
  comment_id: string
}

Sources: packages/web-core/src/shared/hooks/useAzureAttachments.ts

Git Integration

Worktree-Based Development

Vibe Kanban creates isolated git worktrees for each task attempt, enabling:

• Parallel development on multiple features
• Clean separation between task branches
• Easy diff viewing of agent changes

Supported Git Operations

Backend Server (Rust)

The backend server handles OAuth flows and API requests:

// OAuth flow returns HTML response
Response::builder()
    .status(StatusCode::OK)
    .header("content-type", "text/html; charset=utf-8")
    .body(body)

Sources: crates/server/src/routes/oauth.rs

Troubleshooting

Common Setup Issues

1. Node Version Mismatch

• Ensure Node.js >= 20.19.0
• Use nvm use or update Node installation

1. CLI Not Found After Build

• Run pnpm build in the npx-cli directory
• Ensure bin directory is in PATH

1. Authentication Failures

• Verify coding agent authentication
• Check GitHub CLI authentication with gh auth status

Documentation

For more information, visit:

• Official Documentation
• Self-Hosting Guide
• Supported Coding Agents
• GitHub Discussions

Contributing

Ideas and changes should be raised via:

1. GitHub Discussions
2. Discord

Sources: README.md:45-50

Related Pages

Related topics: Crate Reference, Database and Data Models, Coding Agent Executors

Backend Architecture

Overview

Vibe Kanban's backend is built with Rust using the Axum web framework, providing a high-performance API server that handles workspace management, authentication, and integration with coding agents. The backend follows a modular architecture with clear separation between routing, runtime management, and core server functionality.

The server component (crates/server) serves as the central hub for coordinating between the web frontend and various external services including GitHub integrations, coding agent executors, and development workspace environments.

Architecture Components

Core Server Structure

The backend is organized into several key modules:

Module Hierarchy

graph TD
    A[crates/server] --> B[main.rs]
    A --> C[lib.rs]
    A --> D[startup.rs]
    A --> E[routes/]
    A --> F[runtime/]
    E --> E1[oauth.rs]
    E --> E2[mod.rs]
    F --> F1[mod.rs]

Request Flow

graph LR
    A[Client Request] --> B[Axum Router]
    B --> C[Route Handlers]
    C --> D[OAuth Routes]
    C --> E[API Routes]
    C --> F[Runtime Routes]
    D --> G[OAuth Callback]
    E --> H[JSON Response]
    F --> I[Agent Execution]

Routing System

Route Organization

The routing layer in crates/server/src/routes/mod.rs acts as a central router that aggregates all HTTP endpoints. Routes are organized by functional domain:

• OAuth Routes (routes/oauth.rs) - Handle GitHub authentication and OAuth callbacks
• API Routes - Handle workspace operations, task management, and agent interactions
• Runtime Routes (runtime/mod.rs) - Manage coding agent execution contexts

OAuth Implementation

The OAuth route handler in crates/server/src/routes/oauth.rs demonstrates the server's response pattern for authentication flows:

Response::builder()
    .status(StatusCode::OK)
    .header("content-type", "text/html; charset=utf-8")
    .body(body)
    .unwrap()

Sources: crates/server/src/routes/oauth.rs:20-25

The OAuth callback returns an HTML response with embedded base64-encoded app icon, displaying a success message and instructions to return to the application.

Startup Sequence

graph TD
    A[main.rs entry] --> B[Initialize Config]
    B --> C[Load Environment]
    C --> D[startup.rs::run]
    D --> E[Build Router]
    E --> F[Bind Socket]
    F --> G[Start Axum Server]
    G --> H[Listen for Requests]

The startup module (crates/server/src/startup.rs) handles:

• Configuration loading from environment variables
• Router construction with middleware
• Socket binding and server initialization

Runtime Management

Agent Execution Model

The runtime module (crates/server/src/runtime/mod.rs) manages the lifecycle of coding agent processes within workspaces. Each workspace provides an agent with:

Sources: crates/server/src/runtime/mod.rs

Process Tracking

The backend tracks agent processes with metadata including:

• started_at - Process initialization timestamp
• completed_at - Process termination timestamp
• isRunning - Active execution state
• filesChanged - Modified file count
• linesAdded / linesRemoved - Change statistics

State Management

Workspace States

stateDiagram-v2
    [*] --> Draft
    Draft --> Running: Start Agent
    Running --> Completed: Agent Finishes
    Running --> Error: Execution Failure
    Completed --> Archived: User Archives
    Error --> Running: Retry
    Archived --> [*]
    Draft --> [*]: Cancel

Workspaces maintain states including draft, running, completed, and archived, allowing users to manage multiple concurrent agent execution contexts.

API Response Patterns

The backend uses standard HTTP response patterns with JSON payloads:

Frontend Integration

The web-core package (packages/web-core/src/shared/) interacts with the backend through:

• Dialog Components - Modal interfaces for OAuth setup, force push, workspace selection
• Store Hooks - State management via useWorkspaceDiffStore, useUiPreferencesStore
• API Hooks - Data fetching through useAzureAttachments for file handling

Sources: crates/server/src/lib.rs Sources: crates/web-core/src/shared/stores/useWorkspaceDiffStore.ts Sources: crates/web-core/src/shared/hooks/useAzureAttachments.ts

Configuration

The server reads configuration from environment variables with sensible defaults for:

• Server host and port
• Database connection strings
• OAuth client credentials
• Agent executor profiles

Dependencies

Key Rust dependencies for the backend:

Sources: crates/server/src/main.rs Sources: crates/server/src/routes/mod.rs

Related Pages

Related topics: Crate Reference, Backend Architecture

Frontend Architecture

Overview

Vibe Kanban implements a modern, component-driven frontend architecture designed for complex project management workflows involving AI coding agents. The frontend is organized as a monorepo using a layered package structure that separates concerns between UI primitives, business logic, and deployment variants.

The architecture follows these core principles:

• Component Reusability: Shared UI components across multiple deployment contexts
• State Centralization: Global state management via Zustand stores
• Provider Pattern: Context-based dependency injection for cross-cutting concerns
• Type Safety: Full TypeScript coverage with strict typing

Monorepo Structure

The project uses a monorepo architecture with the following key packages:

vibe-kanban/
├── packages/
│   ├── ui/                      # Shared UI primitives
│   │   └── src/components/
│   │       ├── CommandBar.tsx
│   │       ├── KanbanBoard.tsx
│   │       └── WorkspacesSidebar.tsx
│   ├── web-core/                # Core business logic
│   │   └── src/
│   │       ├── shared/
│   │       │   ├── hooks/       # useActions, useAzureAttachments
│   │       │   ├── providers/   # WorkspaceProvider
│   │       │   ├── stores/      # Zustand state stores
│   │       │   └── dialogs/     # Modal components
│   │       └── pages/
│   ├── local-web/               # Local app entry point
│   └── remote-web/              # Remote/server-connected variant
└── npx-cli/                     # CLI entry point

Application Entry Points

Local Web Application

The local web application serves as the standalone deployment variant that runs entirely in the browser without requiring a backend server.

// packages/local-web/src/routes/_app.tsx
// Main entry point for local deployment

Remote Web Application

The remote web application connects to a backend server for persistent storage and multi-user collaboration features.

// packages/remote-web/src/app/entry/App.tsx
// Main entry point for remote deployment

State Management

UI Preferences Store

The application uses Zustand for centralized state management. The useUiPreferencesStore handles UI-specific state including sidebar visibility, panel sizes, and layout modes.

// packages/web-core/src/shared/stores/useUiPreferencesStore.ts
interface UiPreferencesState {
  // Layout state
  layoutMode: 'workspaces' | 'kanban';
  isLeftSidebarVisible: boolean;
  isRightSidebarVisible: boolean;
  isTerminalVisible: boolean;
  
  // Panel states per workspace
  workspacePanelStates: Record<string, WorkspacePanelState>;
  
  // Pane configurations
  paneSizes: Record<string, number>;
  collapsedPaths: Record<string, string[]>;
}

Key state transitions supported by the store:

Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts:1-50

Workspace Provider

The WorkspaceProvider is a React context provider that manages workspace-scoped state and operations.

// packages/web-core/src/shared/providers/WorkspaceProvider.tsx
// Provides workspace context to child components

Core UI Components

KanbanBoard

The KanbanBoard component is the central UI element for task visualization and management. It renders the drag-and-drop interface for issues across different status columns.

// packages/ui/src/components/KanbanBoard.tsx

The board supports multiple item types rendered through consistent interface patterns:

Sources: packages/ui/src/components/CommandBar.tsx:1-50

CommandBar

The CommandBar component provides a keyboard-driven interface for navigation and actions. It groups items by category and supports fuzzy search through labels.

// packages/ui/src/components/CommandBar.tsx

WorkspacesSidebar

The WorkspacesSidebar displays workspace summaries with multiple layout modes:

• List Layout: Flat vertical list with sections for active, archived, and needs-attention workspaces
• Accordion Layout: Collapsible sections with header persistence

// packages/ui/src/components/WorkspacesSidebar.tsx

Workspace summaries display:

• Workspace name and active state
• Running status and pending approvals
• Dev server status
• PR status
• Activity indicators (unseen activity flag)
• Git statistics (files changed, lines added/removed)

Sources: packages/ui/src/components/WorkspacesSidebar.tsx:1-80

Dialog System

Dialog Architecture

The application uses a modal dialog system for complex interactions. Dialogs are defined using the defineModal higher-order function pattern.

// Example dialog pattern
export const ForcePushDialog = defineModal<ForcePushDialogProps, string>(
  ForcePushDialogImpl
);

Dialog Types

ResolveConflictsDialog

Handles git merge conflicts by displaying conflicted files and providing agent selection for resolution.

// packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx

{conflictedFiles.slice(0, 5).map((file) => (
  <li key={file} className="truncate">{file}</li>
))}
{conflictedFiles.length > 5 && (
  <li>And {conflictedFiles.length - 5} more...</li>
)}

The dialog includes:

• Conflicted file list with truncation for large conflicts
• Agent selector for AI-powered resolution
• Config selector for resolution parameters
• New session toggle for existing workspace sessions

Sources: packages/web-core/src/shared/dialogs/tasks/ResolveConflictsDialog.tsx:80-100

Kanban Issue Panel

The KanbanIssuePanelContainer renders detailed issue views with multiple collapsible sections:

// packages/web-core/src/pages/kanban/KanbanIssuePanelContainer.tsx

<IssuePanel
  renderWorkspacesSection={(issueId) => <IssueWorkspacesSectionContainer issueId={issueId} />}
  renderRelationshipsSection={(issueId) => <IssueRelationshipsSectionContainer issueId={issueId} />}
  renderSubIssuesSection={(issueId) => <IssueSubIssuesSectionContainer issueId={issueId} />}
  renderCommentsSection={(issueId) => <IssueCommentsSectionContainer issueId={issueId} />}
/>

Issue Panel Sections

Hooks System

useActions Hook

Custom hooks encapsulate business logic and provide clean interfaces for components.

// packages/web-core/src/shared/hooks/useActions.ts
// Centralizes action dispatching and state updates

useAzureAttachments Hook

Handles file upload workflows with progress tracking:

// packages/web-core/src/shared/hooks/useAzureAttachments.ts

// Progress tracking for uploads
setPendingAttachments((prev) =>
  prev.map((p) =>
    p.file === file ? { ...p, status: 'confirming', progress: 100 } : p
  ))
);

The hook manages:

• Pending attachment states
• Upload progress tracking
• Confirmation workflows
• Completed attachment tracking

Component Interaction Flow

graph TD
    A[App Entry Point] --> B[WorkspaceProvider]
    A --> C[UiPreferencesStore]
    B --> D[KanbanBoard]
    B --> E[WorkspacesSidebar]
    D --> F[KanbanIssuePanelContainer]
    F --> G[Dialog System]
    E --> H[CommandBar]
    G --> I[ForcePushDialog]
    G --> J[ResolveConflictsDialog]
    G --> K[WorkspaceSelectionDialog]
    
    C --> L[Layout Toggle]
    C --> M[Sidebar Visibility]
    C --> N[Terminal Toggle]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

Home Page Structure

The remote web application provides a structured home page with organization and project navigation:

// packages/remote-web/src/pages/HomePage.tsx

function OrganizationSection({ organization, projects, hostId, onRequireHost }) {
  return (
    <section>
      <header>
        <h2>{organization.name}</h2>
        <p>{projects.length} {projects.length === 1 ? "project" : "projects"}</p>
      </header>
      <ul className="grid">
        {projects.map((project) => <ProjectCard project={project} />)}
      </ul>
    </section>
  );
}

Deployment Variants

The application supports two deployment modes:

graph LR
    subgraph Local["Local Deployment"]
        L1[local-web package]
        L2[Browser-only execution]
        L3[No server required]
    end
    
    subgraph Remote["Remote Deployment"]
        R1[remote-web package]
        R2[Backend server connection]
        R3[Multi-user support]
    end
    
    style Local fill:#bbdefb
    style Remote fill:#c8e6c9

Local Web

• Runs entirely in the browser
• No backend server required
• Single-user mode
• Data stored in browser storage

Remote Web

• Requires backend server (crates/server)
• Multi-user support via OAuth authentication
• Persistent storage in database
• Real-time collaboration features

Technology Stack

Key Architectural Patterns

1. Provider Pattern

Cross-cutting concerns are injected via React context providers:

// Workspace context available throughout the component tree
<WorkspaceProvider>
  <KanbanBoard />
  <WorkspacesSidebar />
</WorkspaceProvider>

2. Store Pattern

Zustand stores provide centralized, typed state with simple update functions:

// Simple store usage
const { layoutMode, toggleLayoutMode } = useUiPreferencesStore();

3. Modal Definition Pattern

Dialogs use a higher-order function for consistent modal lifecycle management:

export const SomeDialog = defineModal<TProps, TResult>(Component);

4. Lazy Loading

Components support dynamic imports for code splitting:

// Dialogs loaded on demand to reduce initial bundle size
const SomeDialog = lazy(() => import('./dialogs/SomeDialog'));

Related Pages

Related topics: Backend Architecture, Coding Agent Executors, Relay and Remote Access

Crate Reference

Overview

Vibe Kanban is a monorepo with a multi-package architecture that combines Rust-based backend services (crates) with TypeScript/React frontend packages. The backend crates provide core infrastructure for workspace management, code execution, database operations, and secure communication.

The project structure includes:

• Frontend packages (packages/): React-based UI including web-core, ui, and remote-web
• Rust crates (crates/): Backend services for server operations, API types, database, executors, MCP protocol, relay tunneling, workspace management, and worktree management

Crate Architecture

The Rust backend consists of several specialized crates that work together to provide the core functionality of Vibe Kanban:

Server Crate

The server crate (crates/server/src/) is the main entry point for the backend application. It handles HTTP routing and serves both the API endpoints and static assets.

OAuth Routes

The server provides OAuth authentication flow endpoints for GitHub integration:

File: crates/server/src/routes/oauth.rs

The OAuth handler returns an HTML page confirming successful authentication:

Response::builder()
    .status(StatusCode::OK)
    .header("content-type", "text/html; charset=utf-8")
    .body(body)
    .unwrap()

The response includes:

• Application logo embedded as base64 PNG
• Success message display
• User instruction to close the tab and return to the app

Project Organization

Monorepo Structure

vibe-kanban/
├── packages/
│   ├── web-core/      # Core web UI components
│   ├── ui/            # Shared UI components
│   └── remote-web/    # Remote access web interface
├── crates/
│   ├── server/        # HTTP server
│   ├── api-types/     # API type definitions
│   ├── db/            # Database layer
│   ├── executors/     # Agent execution engine
│   ├── relay-tunnel/   # Relay communication
│   ├── mcp/           # MCP protocol
│   ├── workspace-manager/  # Workspace operations
│   └── worktree-manager/   # Git worktree management
└── public/            # Static assets

Data Flow Architecture

graph TD
    subgraph Frontend["Frontend (TypeScript/React)"]
        UI[UI Components]
        WC[Web Core]
    end
    
    subgraph Backend["Backend (Rust Crates)"]
        Server[Server Crate]
        DB[(Database)]
        API[API Types]
    end
    
    subgraph Execution["Execution Layer"]
        Exec[Executors]
        WM[Workspace Manager]
        WTM[Worktree Manager]
        MCP[MCP Protocol]
        RT[Relay Tunnel]
    end
    
    UI --> WC
    WC --> Server
    Server --> DB
    Server --> API
    Exec --> WM
    WM --> WTM
    Exec --> MCP
    Exec --> RT

Key Modules

API Types

The api-types crate provides shared type definitions used across the frontend and backend for type-safe API communication.

Database Layer

The db crate handles persistent storage operations, including:

• Workspace state persistence
• User preferences
• Project and organization data

Workspace Manager

Manages the lifecycle of workspaces, including creation, archival, and state tracking.

Worktree Manager

Handles Git worktree operations, providing isolated branch environments for each workspace.

Executors

The execution engine that runs coding agents (Claude Code, Codex, Gemini CLI, etc.) within workspace environments.

Relay Tunnel

Provides secure communication channels for remote access scenarios.

MCP Integration

Implements the Model Context Protocol for enhanced agent capabilities.

Configuration and Preferences

The frontend manages user preferences through the useUiPreferencesStore, which handles:

Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts

Development Workflow

The system supports the following developer keyboard shortcuts:

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts

Summary

The Vibe Kanban architecture combines TypeScript/React frontend packages with Rust backend crates to provide a comprehensive coding agent workspace management system. The Rust crates handle core infrastructure including database operations, workspace lifecycle, Git worktree management, code execution, and secure communication, while the frontend provides the user interface for planning, reviewing, and managing coding agent activities.

For the latest updates and project status, refer to the official announcement at vibekanban.com/blog/shutdown.

Related Pages

Related topics: Crate Reference, MCP Server Integration

Coding Agent Executors

Overview

Coding Agent Executors in Vibe Kanban are the runtime engines that enable AI coding agents to execute tasks within isolated workspace environments. Each workspace provides an agent with a dedicated branch, terminal, and dev server, allowing software engineers to plan work through kanban issues while agents perform the actual coding tasks.

The executor system supports multiple AI coding agents, enabling teams to choose the most appropriate agent for their specific needs or switch between agents based on task requirements.

Sources: README.md:1-20

Supported Agents

Vibe Kanban supports the following coding agents:

Sources: README.md:25

Architecture

Executor Components

The executor system consists of several key components:

1. Session Chat Box - The primary interface for interacting with coding agents during task execution
2. Conversation List - Displays the ongoing conversation and output between the agent and user
3. Process Management - Handles the lifecycle of agent processes including start, execution, and completion
4. Workspace Integration - Provides isolated environments with git branches, terminals, and dev servers

graph TD
    A[Kanban Issue] --> B[Workspace Creation]
    B --> C[Session Chat Box]
    C --> D[Agent Executor]
    D --> E[Conversation List]
    D --> F[Process Execution]
    F --> G[Branch & Terminal]
    F --> H[Dev Server]
    E --> I[Diff Review]
    I --> J[Inline Comments]
    J --> K[Pull Request]

Sources: packages/web-core/src/features/workspace-chat/ui/SessionChatBoxContainer.tsx:1-50

Session Chat Box

The SessionChatBox component is the central hub for agent interaction. It manages the chat interface, editor input, and session state.

Key Properties

Session State Management

session={{
  sessions: [],
  selectedSessionId: undefined,
  onSelectSession: () => {},
  isNewSessionMode: false,
  onNewSession: undefined,
}}

The session object tracks the active conversation context, allowing users to switch between multiple agent sessions within a workspace.

Sources: packages/web-core/src/features/workspace-chat/ui/SessionChatBoxContainer.tsx:60-100

Conversation Display

The ConversationList component renders the ongoing interaction with the coding agent.

Entry Types

graph LR
    A[Agent Output] --> B{Entry Type?}
    B -->|STDOUT| C[Paragraph Display]
    B -->|STDERR| D[Error Display]
    B -->|NORMALIZED| E[DisplayConversationEntry]
    B -->|THINKING| F[Aggregated Thinking]

Sources: packages/web-core/src/features/workspace-chat/ui/ConversationListContainer.tsx:40-70

Process Execution

The ProcessesTab component provides visibility into running and completed agent processes.

Process Information Displayed

• Process Status - Current state (running, completed, failed)
• Started At - Process initiation timestamp
• Completed At - Process completion timestamp (when applicable)
• Log Output - Real-time and archived process logs

Log Management

The ProcessesTab includes functionality to copy logs to clipboard for debugging and audit purposes:

const handleCopyLogs = () => {
  // Copies all accumulated logs to clipboard
  // Updates UI to show "Logs copied" confirmation
};

Sources: packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx:1-80

Workspace Shortcuts

Agent-related operations can be triggered via keyboard shortcuts defined in useWorkspaceShortcuts:

Sources: packages/web-core/src/shared/keyboard/useWorkspaceShortcuts.ts:1-30

Workspace Selection

When linking an issue to a workspace, users can select from available workspaces or create new ones:

interface Workspace {
  id: string;
  name: string;
  branch: string;
  isArchived: boolean;
  filesChanged: number;
  linesAdded: number;
  linesRemoved: number;
  isRunning: boolean;
  isPinned: boolean;
  hasPendingApproval: boolean;
  hasRunningDevServer: boolean;
  hasUnseenActivity: boolean;
  latestProcessCompletedAt: Date | null;
  latestProcessStatus: string | null;
  prStatus: string | null;
}

Sources: packages/web-core/src/shared/dialogs/command-bar/WorkspaceSelectionDialog.tsx:50-90

Executor Profile Configuration

Each executor can be configured with specific profiles that define:

• Model Selection - Which AI model to use (e.g., Claude 3.5 Sonnet, GPT-4)
• System Prompt - Custom instructions for the agent
• Temperature - Response randomness setting
• Max Tokens - Response length limits

Profiles are stored in default_profiles.json and can be selected per-workspace or globally.

Workflow Summary

graph TD
    A[Create Kanban Issue] --> B[Open/Create Workspace]
    B --> C[Select Agent & Profile]
    C --> D[Start Agent Session]
    D --> E[Agent Reads Issue Context]
    E --> F[Agent Executes Tasks]
    F --> G[Changes Applied to Branch]
    G --> H[Review Diff in UI]
    H --> I{Changes Approved?}
    I -->|Yes| J[Create Pull Request]
    I -->|No| K[Send Feedback to Agent]
    K --> F
    J --> L[Merge PR]

Related Components

Related Pages

Related topics: Coding Agent Executors, Database and Data Models

The requested MCP-related source files were not included in the provided context. The `

Relay and Remote Access

Overview

The Relay and Remote Access system in Vibe Kanban enables secure, low-latency communication between local development environments and remote hosts. This system allows users to access their coding workspaces and development servers from anywhere while maintaining proper authentication and origin verification.

The relay architecture consists of multiple layers:

• Relay Tunnel - Handles encrypted tunneled connections
• Relay WebRTC - Provides peer-to-peer communication channels
• Relay Hosts - Manages the registry and lifecycle of remote hosts
• Relay Protocol - Defines the communication protocol between clients and hosts
• Relay Client - Implements the client-side connection logic

Architecture

System Components

Connection Flow

graph TD
    A[Client Browser] -->|HTTPS + Relay Header| B[Server Middleware]
    B -->|Verify Origin| C{Origin Valid?}
    C -->|Yes| D[Relay Host Lookup]
    C -->|No| E[403 Forbidden Response]
    D -->|Host Online| F[Establish WebSocket]
    D -->|Host Unpaired| G[Pairing Flow]
    F -->|Tunnel Established| H[Remote Workspace Access]
    G -->|Paired Successfully| F

Origin Verification Middleware

The server implements an origin.rs middleware that validates all incoming requests to ensure they originate from legitimate sources.

Key Components

RELAY_HEADER Constant The relay header (x-vibe-relay) identifies requests coming through the relay system. When present with value "1", the request is flagged as a relay request.

Sources: crates/server/src/middleware/origin.rs:1-5

Header Retrieval Functions

fn is_relay_request<B>(req: &Request<B>) -> bool {
    req.headers()
        .get(RELAY_HEADER)
        .and_then(|v| v.to_str().ok())
        .is_some_and(|v| v.trim() == "1")
}

Sources: crates/server/src/middleware/origin.rs:15-21

Host Normalization The normalize_host function standardizes host strings for consistent comparison:

1. Trims whitespace and IPv6 brackets
2. Converts to lowercase
3. Converts localhost aliases to "localhost"
4. Converts loopback IPs to "localhost"
5. Returns normalized IP or hostname

fn normalize_host(host: &str) -> String {
    let trimmed = host.trim().trim_start_matches('[').trim_end_matches(']');
    let lower = trimmed.to_ascii_lowercase();
    if lower == "localhost" {
        return "localhost".to_string();
    }
    if let Ok(ip) = lower.parse::<IpAddr>() {
        if ip.is_loopback() {
            return "localhost".to_string();
        }
        return ip.to_string();
    }
    lower
}

Sources: crates/server/src/middleware/origin.rs:31-45

Origin Matching The origin_matches_host function validates that the request origin corresponds to the host header:

fn origin_matches_host(origin: &str, host: &str) -> bool {
    origin
        .strip_prefix("http://")
        .or_else(|| origin.strip_prefix("https://"))
        .is_some_and(|rest| rest.eq_ignore_ascii_case(host))
}

Sources: crates/server/src/middleware/origin.rs:26-29

Forbidden Response

When origin verification fails, the middleware returns a 403 Forbidden response:

fn forbidden() -> Response {
    Response::builder()
        .status(StatusCode::FORBIDDEN)
        .body(Body::empty())
        .unwrap_or_else(|_| Response::new(Body::empty()))
}

Sources: crates/server/src/middleware/origin.rs:23-25

Remote Host Management

Host Status Types

The UI displays host status with visual indicators:

const isOnline = host.status === "online";
const isUnpaired = host.status === "unpaired";
const isClickable = isOnline || isUnpaired;

Sources: packages/remote-web/src/app/layout/RemoteAppShell.tsx:1-50

Host Display

Hosts are rendered with status indicators using color coding:

<span className={cn(
    "h-2 w-2 shrink-0 rounded-full",
    isOnline
      ? "bg-success"
      : isUnpaired
        ? "border border-warning bg-white"
        : "bg-low",
)}

Sources: packages/remote-web/src/app/layout/RemoteAppShell.tsx:45-53

Host Connection Handler

onClick={() => {
    handleHostClick(host.id, host.status);
    setIsDrawerOpen(false);
}}

Sources: packages/remote-web/src/app/layout/RemoteAppShell.tsx:38-41

Relay Pairing System

Pairing Errors

The error handling system maps various pairing errors to appropriate HTTP responses:

RelayPairingClientError::RemoteClient(ref inner) => {
    tracing::warn!(%inner, "Relay host pairing authentication failed");
    ApiError::Unauthorized
}
RelayPairingClientError::Pairing(ref detail) => {
    tracing::warn!(%detail, "Relay host pairing failed");
    ApiError::BadRequest(err.to_string())
}

Sources: crates/server/src/error.rs:1-30

Unconfigured Relay

When the relay API is not configured, the system returns:

from(_: RelayHostsNotConfigured) -> Self {
    ApiError::BadRequest("Remote relay API is not configured".to_string())
}

Sources: crates/server/src/error.rs:45-48

Attachment Upload via Relay

The relay system also handles file attachments when working remotely. The upload process involves:

1. Initialize upload with Azure blob storage
2. Upload chunks with progress tracking
3. Confirm upload completion

const result = await confirmAttachmentUpload({
    project_id: projectId,
    upload_id: initResult.upload_id,
    filename: file.name,
    content_type: file.type,
    size_bytes: file.size,
    hash,
    issue_id: issueIdRef.current,
    comment_id: commentIdRef.current,
});

Sources: packages/web-core/src/shared/hooks/useAzureAttachments.ts:1-50

Workspace Panel States

The relay system integrates with the workspace panel state management:

toggleLeftMainPanel: (workspaceId) => {
    if (!workspaceId) return;
    const state = get();
    const wsState = state.workspacePanelStates[workspaceId] ?? DEFAULT_WORKSPACE_PANEL_STATE;
    if (wsState.isLeftMainPanelVisible && wsState.rightMainPanelMode === null)
        return;
    set({
        workspacePanelStates: {
            ...state.workspacePanelStates,
            [workspaceId]: {
                ...wsState,
                isLeftMainPanelVisible: !wsState.isLeftMainPanelVisible,
            },
        },
    });
},

Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts:1-40

Security Considerations

CORS and Origin Validation

All relay requests undergo strict origin validation:

1. Requests must include a valid Origin header
2. The origin must match the Host header (with protocol prefix stripped)
3. Relay requests are identified via the x-vibe-relay header
4. Loopback addresses and localhost are normalized for consistent comparison

Authentication Flow

sequenceDiagram
    participant C as Client
    participant S as Server
    participant R as Relay Host
    
    C->>S: Request with x-vibe-relay: 1
    S->>S: Validate Origin matches Host
    alt Valid Request
        S->>R: Relay connection
        R-->>C: Authenticated tunnel
    else Invalid Origin
        S-->>C: 403 Forbidden
    end

Configuration

Environment Variables

Default Port Resolution

The system includes logic for determining default ports based on HTTPS configuration:

fn default_port(https: bool)

Sources: crates/server/src/middleware/origin.rs:50

Troubleshooting

Common Issues

Diagnostic Steps

1. Verify the x-vibe-relay header is present in requests
2. Check server logs for relay-related warnings and errors
3. Confirm host status in the Remote App Shell UI
4. Validate origin normalization with normalize_host() function

Related Pages

Related topics: Backend Architecture, Key Concepts

Database and Data Models

Overview

Vibe Kanban uses a Rust-based database layer (crates/db) for persistent storage, with shared API types defined in crates/api-types. The architecture separates concerns between the database implementation, business logic, and the web frontend, enabling type-safe data flow across the application.

Architecture Overview

graph TD
    A[Web Frontend<br/>packages/web-core] --> B[API Types<br/>crates/api-types]
    C[Remote Web<br/>packages/remote-web] --> B
    B --> D[Database Layer<br/>crates/db]
    D --> E[(SQLite<br/>Database)]
    F[Server<br/>crates/server] --> D

Core Data Models

Workspace Model

The workspace model represents a coding agent execution environment. Each workspace is associated with a specific branch, terminal session, and dev server configuration.

Sources: crates/db/src/models/workspace.rs

Session Model

Sessions represent individual coding agent execution runs within a workspace.

Sources: crates/db/src/models/session.rs

Task Model

Tasks (issues) are the fundamental unit of work in the kanban system.

Sources: crates/db/src/models/task.rs

Project Model

Projects organize tasks and workspaces into logical units.

Sources: crates/db/src/models/project.rs

Repository Model

Repository configurations link external Git repositories to the system.

Sources: crates/db/src/models/repo.rs

API Types System

The crates/api-types crate defines shared TypeScript types used across the frontend packages. These types ensure type safety between the server and client applications.

Key Type Exports

The API types module re-exports types from the database models and extends them with frontend-specific metadata:

// Shared type definitions for workspace state
interface WorkspaceState {
  workspaceId: string;
  branchName: string;
  filesChanged: number;
  linesAdded: number;
  linesRemoved: number;
  isRunning: boolean;
  isPinned: boolean;
  hasPendingApproval: boolean;
  hasRunningDevServer: boolean;
  hasUnseenActivity: boolean;
  latestProcessCompletedAt: string | null;
  latestProcessStatus: ProcessStatus;
  prStatus: PRStatus | null;
}

Sources: crates/api-types/src/lib.rs

State Management Integration

Workspace Diff Store

The frontend uses Zustand stores to manage client-side state that syncs with the database models.

// From packages/web-core/src/shared/stores/useWorkspaceDiffStore.ts
export const useGetGitHubCommentCountForFile = () =>
  useWorkspaceDiffStore((s) => s.getGitHubCommentCountForFile);

export const useGetFilesWithGitHubComments = () =>
  useWorkspaceDiffStore((s) => s.getFilesWithGitHubComments);

UI Preferences Store

User interface preferences are persisted and managed through a dedicated store:

Sources: packages/web-core/src/shared/stores/useUiPreferencesStore.ts

Data Flow Architecture

graph LR
    A[User Action] --> B[React Component]
    B --> C[Zustand Store]
    C --> D[API Client]
    D --> E[Rust Server<br/>crates/server]
    E --> F[Database Layer<br/>crates/db]
    F --> G[(SQLite)]
    G --> F
    F --> E
    E --> D
    D --> C
    C --> B

Relationships Between Models

erDiagram
    PROJECT ||--o{ TASK : contains
    PROJECT ||--o{ WORKSPACE : contains
    PROJECT ||--o{ REPO : links
    TASK ||--o{ SESSION : executes
    WORKSPACE ||--o{ SESSION : contains
    REPO ||--o{ WORKSPACE : checked_out

Database Module Structure

The database crate (crates/db) is organized into the following modules:

Sources: crates/db/src/lib.rs, crates/db/src/models/mod.rs

Attachment Management

The system supports file attachments associated with tasks and comments:

Sources: packages/web-core/src/shared/hooks/useAzureAttachments.ts

Process Tracking

The system tracks coding agent processes with the following states:

Sources: packages/web-core/src/shared/components/tasks/TaskDetails/ProcessesTab.tsx

Summary

The Vibe Kanban database layer provides a type-safe, Rust-based persistence system with clear separation between:

1. Core Entities: Workspace, Session, Task, Project, and Repository models define the data structure
2. API Types: Shared TypeScript types ensure consistency across frontend packages
3. State Management: Zustand stores provide reactive client-side state synchronized with server data
4. Relationships: Well-defined foreign key relationships enable complex queries and data navigation

This architecture enables the application to manage coding agent workflows efficiently while maintaining data integrity and type safety throughout the stack.

Related Pages

Related topics: Relay and Remote Access, Development Setup

Deployment and Infrastructure

Overview

Vibe Kanban provides flexible deployment options ranging from local development to production-grade Docker-based self-hosting. The infrastructure supports both single-machine deployments and distributed architectures with optional relay tunneling for remote access. Sources: README.md:1-60

The project uses a monorepo structure with the following key deployment components:

Architecture Overview

Vibe Kanban's deployment architecture consists of multiple Docker containers orchestrated via Docker Compose. The system supports three deployment profiles: default, relay, and attachments.

graph TD
    User([User Browser]) --> Caddy[Caddy Reverse Proxy]
    Caddy --> RemoteWeb[remote-web:3001]
    Caddy --> RemoteServer[remote-server:3000]
    
    RemoteServer --> Electric[(Electric SQL<br/>PostgreSQL)]
    RemoteServer --> Azurite[(Azurite<br/>Blob Storage)]
    
    RemoteWeb -->|WebSocket| RelayTunnel[relay-tunnel:8082]
    User -->|Secure Tunnel| RelayTunnel
    
    subgraph Docker Network
        Caddy
        RemoteWeb
        RemoteServer
        Electric
        Azurite
        RelayTunnel
    end

Component Responsibilities

Docker Deployment

Prerequisites

• Docker Engine 24.0+
• Docker Compose v2.20+
• Minimum 4GB RAM available
• 10GB disk space

Quick Start

Clone the repository and navigate to the remote deployment directory:

cd crates/remote
docker compose --env-file .env.remote up --build

This starts the default stack with web UI, API server, and database.

Starting the Development Stack

From the repository root:

pnpm run remote:dev

For full stack with relay and local attachment storage:

pnpm run remote:dev:full

Equivalent manual command:

cd crates/remote
docker compose --env-file .env.remote --profile relay --profile attachments up --build

Sources: crates/remote/README.md:45-70

Environment Configuration

Required Environment Variables

Generating JWT Secret

Generate a secure JWT secret using OpenSSL:

openssl rand -base64 48

OAuth Configuration

Configure OAuth callback URLs for external authentication:

Sources: crates/remote/README.md:1-50

Docker Compose Profiles

Vibe Kanban uses Docker Compose profiles to enable optional components:

Default Profile

Starts core infrastructure only:

cd crates/remote
docker compose --env-file .env.remote up --build

Services started:

• remote-db (PostgreSQL via Electric SQL)
• remote-server
• remote-web

Relay Profile

Enables remote access via WebSocket tunnel:

cd crates/remote
docker compose --env-file .env.remote --profile relay up --build

Additional service:

• relay-tunnel on port 8082

Attachments Profile

Enables local file storage using Azurite:

cd crates/remote
docker compose --env-file .env.remote --profile attachments up --build

Additional service:

• azurite on ports 10000/10001/10002

Combined Profiles

Enable both relay and attachments:

cd crates/remote
docker compose --env-file .env.remote --profile relay --profile attachments up --build

Local HTTPS with Caddy

For development environments requiring HTTPS, Caddy serves as a reverse proxy with automatic TLS certificate management.

Install Caddy

macOS:

brew install caddy

Debian/Ubuntu:

sudo apt install caddy

Configuration

The repository includes Caddyfile.example with the required routing configuration. Start Caddy from the repository root:

caddy run --config Caddyfile.example

On first run, Caddy installs a local CA certificate and may prompt for administrator password.

Endpoint Routing

Sources: crates/remote/README.md:15-45

Health Check Endpoints

Verify deployment health:

curl -sk https://localhost:3001/v1/health
curl -sk https://relay.localhost:3001/health

If the relay health endpoint returns HTML instead of {"status":"ok"}, the Caddy host routing configuration is incorrect.

Database Infrastructure

Electric SQL with PostgreSQL

Vibe Kanban uses Electric SQL for database synchronization, providing:

• Real-time data sync across instances
• Offline-first capability
• PostgreSQL compatibility

Connection Configuration

Container Networking

All services communicate through the Docker bridge network, with the database accessible only to internal services.

Relay Tunnel Service

The relay tunnel enables secure remote access to Vibe Kanban when deployed behind NAT or firewalls.

sequenceDiagram
    participant Client as Remote Client
    participant Relay as relay-tunnel:8082
    participant WebUI as remote-web:3001
    participant Server as remote-server:3000
    
    Client->>Relay: WebSocket Connection
    Relay->>WebUI: Forward WebSocket
    WebUI->>Server: API Request
    Server-->>WebUI: Response
    WebUI-->>Relay: WebSocket Response
    Relay-->>Client: Tunneled Response

Requirements

• relay profile enabled in Docker Compose
• VK_SHARED_RELAY_API_BASE environment variable set
• Caddy configured with relay.localhost:3001 route

Attachment Storage

Azure Blob Storage (Production)

Production deployments should configure Azure Blob Storage for file attachments:

Azurite (Development)

Local development uses Azurite, an Azure Storage emulator:

azurite:
  image: mcr.microsoft.com/azure-storage/azurite
  ports:
    - "10000:10000"  # Blob service
    - "10001:10001"  # Queue service
    - "10002:10002"  # Table service

Sources: crates/remote/README.md:70-95

API Endpoints Reference

Health Check Endpoints

OAuth Endpoints

Deployment States

stateDiagram-v2
    [*] --> Initializing
    Initializing --> StartingServices: docker compose up
    StartingServices --> DatabaseReady: PostgreSQL online
    DatabaseReady --> APIServerReady: Server responding
    APIServerReady --> WebUIAvailable: UI accessible
    WebUIAvailable --> RelayEnabled: relay profile active
    RelayEnabled --> [*]: Services running
    
    Initializing --> Failed: Container error
    StartingServices --> Failed: Port conflict
    APIServerReady --> Degraded: Health check failing
    Degraded --> APIServerReady: Auto-recovery
    Failed --> Initializing: Restart triggered

Development vs Production

Development Stack

Production Stack

Troubleshooting

Container Startup Failures

``bash lsof -i :3000 -i :3001 -i :5433 -i :8082 ``

1. Check port availability:

``bash docker compose --env-file .env.remote config ``

1. Verify environment variables are set:

``bash docker compose --env-file .env.remote logs -f ``

1. Check container logs:

Database Connection Issues

``bash docker compose ps remote-db ``

1. Ensure database container is healthy:

``bash psql "postgres://remote:remote@localhost:5433/remote" ``

1. Test connection manually:

Relay Tunnel Not Working

``bash curl -sk https://relay.localhost:3001/health ``

1. Verify Caddy routing for relay.localhost:

``bash docker compose logs relay-tunnel ``

1. Check relay container logs:

1. Ensure firewall allows WebSocket connections on port 8082

OAuth Configuration Errors

Ensure OAuth callback URLs in your provider settings match exactly:

• Protocol: https:// (not http://)
• Port: 3001 (unless custom configured)
• Path: /v1/oauth/{provider}/callback

Security Considerations

Network Isolation

All internal services communicate within the Docker network without exposure to the host:

networks:
  default:
    driver: bridge
    internal: false

Secret Management

• Never commit .env.remote to version control
• Use Docker secrets for production deployments
• Rotate JWT_SECRET periodically

TLS Requirements

• Use HTTPS in all production deployments
• Configure Caddy with valid certificates for OAuth providers
• Some OAuth providers require HTTPS callback URLs

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id))

• Severity: high
• Finding: Installation risk is backed by a source signal: Deployment(Other(Migration failed: error returned from database: (code: 1) no such column: ep.session_id)). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/issues/2972

2. Configuration risk: Support for self-hosted projects and better export

• Severity: high
• Finding: Configuration risk is backed by a source signal: Support for self-hosted projects and better export. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/issues/3396

3. Security or permission risk: [Proposal] JIRA Integration for Vibe Kanban

• Severity: high
• Finding: Security or permission risk is backed by a source signal: [Proposal] JIRA Integration for Vibe Kanban. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/issues/2424

4. Installation risk: Pre-release v0.1.40-20260401153532

• Severity: medium
• Finding: Installation risk is backed by a source signal: Pre-release v0.1.40-20260401153532. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.40-20260401153532

5. Installation risk: Release v0.1.36

• Severity: medium
• Finding: Installation risk is backed by a source signal: Release v0.1.36. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.36-20260323174633

6. Installation risk: Release v0.1.43

• Severity: medium
• Finding: Installation risk is backed by a source signal: Release v0.1.43. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.43-20260417125614

7. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | host_targets=claude, claude_code

8. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | README/documentation is current enough for a first validation pass.

9. Project risk: Pre-release v0.1.39-20260331145823

• Severity: medium
• Finding: Project risk is backed by a source signal: Pre-release v0.1.39-20260331145823. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/releases/tag/v0.1.39-20260331145823

10. Maintenance risk: [Request] Support RDS for self hosting in AWS

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: [Request] Support RDS for self hosting in AWS. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/BloopAI/vibe-kanban/issues/3405

11. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | last_activity_observed missing

12. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1002125012 | https://github.com/BloopAI/vibe-kanban | no_demo; severity=medium

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using Vibe Kanban Capability Pack with real data or production workflows.

• Support for self-hosted projects and better export - github / github_issue
• Deployment(Other(Migration failed: error returned from database: (code: - github / github_issue
• Issue: Unclear Git + Bitbucket Setup for Vibe-Kanban (OpenCode) in Docke - github / github_issue
• [[Proposal] JIRA Integration for Vibe Kanban](https://github.com/BloopAI/vibe-kanban/issues/2424) - github / github_issue
• Git repository is wiped after deleting Vibe Kanban workspace - github / github_issue
• [[Request] Support RDS for self hosting in AWS](https://github.com/BloopAI/vibe-kanban/issues/3405) - github / github_issue
• Release v0.1.43 - github / github_release
• Pre-release v0.1.41-20260403182044 - github / github_release
• Pre-release v0.1.40-20260401153532 - github / github_release
• Pre-release v0.1.39-20260331145823 - github / github_release
• remote-v0.1.26 - github / github_release
• Pre-release v0.1.37-20260327101540 - github / github_release