Install from Source

Build and run Jack The Butler from source code for development or customization.

Installing from source gives you full control over the codebase. This approach is ideal for developers who want to customize Jack or contribute to the project.

Prerequisites

  • Node.js 22+ — Required for modern JavaScript features
  • pnpm 9+ — Package manager (faster than npm)
  • Git — For cloning the repository

Install pnpm if you haven't:

npm install -g pnpm

Clone the Repository

git clone https://github.com/JackTheButler/JackTheButler.git
cd JackTheButler

Install Dependencies

pnpm install

This installs dependencies for all workspaces (backend, dashboard, and landing page).

Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your settings:

# Core settings
NODE_ENV=development
PORT=3000
DATABASE_PATH=./data/jack.db

# Security (generate with: openssl rand -base64 32)
JWT_SECRET=your-jwt-secret-minimum-32-characters-long
ENCRYPTION_KEY=your-encryption-key-minimum-32-chars

Initialize Database

Run migrations to create the database schema:

pnpm db:migrate

Optionally, seed with sample data for development:

pnpm db:seed

Development Mode

Start the development server with hot reload:

pnpm dev

This starts:

  • Backend API at http://localhost:3000
  • Dashboard at http://localhost:5173

You can also run components separately:

# Backend only
pnpm dev:gateway

# Dashboard only
pnpm dev:dashboard

Production Build

Build for production:

pnpm build

Start the production server:

pnpm start

Project Structure

JackTheButler/
├── src/
│   ├── core/           # Business logic (message processing, routing)
│   ├── apps/           # Adapters (AI providers, channels, PMS)
│   ├── gateway/        # HTTP/WebSocket server (Hono)
│   ├── services/       # State management services
│   ├── db/             # Database schema and migrations
│   └── types/          # TypeScript definitions
├── apps/
│   ├── dashboard/      # React staff dashboard
│   └── widget/         # Guest web chat widget
├── data/               # SQLite database (gitignored)
├── tests/              # Test files
└── docs/               # Technical documentation

Useful Commands

Command Description
pnpm dev Start development server
pnpm build Build for production
pnpm test Run tests
pnpm lint Run linter
pnpm typecheck TypeScript type checking
pnpm db:studio Open Drizzle Studio (database GUI)
pnpm db:generate Generate migrations from schema
pnpm db:migrate Run database migrations

Customization

Adding a new AI provider

Create a new adapter in src/apps/ai/providers/ following the pattern in anthropic.ts.

Adding a new channel

Create a new channel adapter in src/apps/channels/ following the pattern in sms/twilio.ts.

Modifying the dashboard

The React dashboard is in apps/dashboard/. It uses Vite, React Router, and Tailwind CSS.

Contributing

We welcome contributions! See the Contributing Guide for:

  • Code style guidelines
  • Pull request process
  • Testing requirements
  • Issue reporting

Next Steps

  1. Complete the Setup Wizard
  2. Review the technical documentation on GitHub
  3. Join the community on GitHub Discussions