Process Management

Learn how to manage processes with Lighthouse.

Overview

Lighthouse can manage your development processes:

• Start and stop services
• Monitor health status
• View process logs
• Restart on changes

Process Configuration

Define processes in your configuration:

processes: [
  {
    id: 'api-server',
    name: 'API Server',
    description: 'Main API backend',
    command: 'pnpm',
    args: ['dev'],
    cwd: './services/api',
    mode: 'auto',
    autoStart: true,
    env: {
      NODE_ENV: 'development',
      PORT: '4005',
    },
    healthCheck: {  // Required
      url: 'http://localhost:4005/health',
      interval: 5000,
      timeout: 3000,
    },
  },
]

Process Modes

Managed Mode

Lighthouse starts and fully manages the process:

{
  id: 'api',
  mode: 'managed',
  command: 'pnpm',
  args: ['dev'],
  cwd: './api',
  healthCheck: {
    url: 'http://localhost:4005/health',
    interval: 5000,
  },
}

• Lighthouse starts the process
• Output is captured and displayed
• Process stops when Lighthouse exits

External Mode

Process runs independently, Lighthouse only monitors:

{
  id: 'database',
  name: 'PostgreSQL',
  mode: 'external',
  command: 'docker',  // Not used for external
  args: ['compose', 'up', 'postgres'],
  cwd: '.',
  healthCheck: {
    url: 'http://localhost:5432',
    interval: 10000,
  },
}

• Process started outside Lighthouse
• Only health check monitoring
• No start/stop control

Auto Mode (Recommended)

Automatically detects the best mode:

{
  id: 'api',
  mode: 'auto',
  command: 'pnpm',
  args: ['dev'],
  cwd: './api',
  healthCheck: {
    url: 'http://localhost:4005/health',
    interval: 5000,
  },
}

• If process is running → external mode
• If process is not running → managed mode

Process Controls

Keyboard Shortcuts

Key	Action
S	Start selected process
X	Stop selected process
R	Restart selected process
A	Start all processes
Shift+X	Stop all processes
H	Check health
L	View logs

Starting Processes

┌─────────────────────────────────────────┐
│  Process Manager                        │
├─────────────────────────────────────────┤
│                                         │
│  > ○ api-server       Stopped           │
│    ○ order-service    Stopped           │
│    ● database         Running (ext)     │
│                                         │
│  [S] Start  [A] Start All               │
│                                         │
└─────────────────────────────────────────┘

Stopping Processes

Select a running process and press X to stop it.

Restarting Processes

Press R to restart a process (stop + start).

Health Checks

The healthCheck field is required for all processes. Configure health checks for automatic monitoring:

healthCheck: {
  url: 'http://localhost:4005/health',  // Required
  interval: 5000,      // Required - Check every 5 seconds (ms)
  timeout: 3000,       // Optional - Fail after 3 seconds (default: 5000)
}

Health Check Options

Option	Type	Required	Default	Description
url	string	✓	-	URL to check health
interval	number	✓	-	Check interval in ms
timeout	number		5000	Timeout per check in ms

Health Status

Status	Description
● Healthy	Health check passing
⚠ Unhealthy	Health check failing
○ Unknown	No health check or process stopped
⟳ Checking	Health check in progress

Process Logs

View logs for a specific process:

1. Select the process
2. Press L to view logs
3. Press Esc to return

Log Features

• Real-time streaming
• Scroll through history
• Filter by log level
• Clear logs

Auto-Start

Enable auto-start to start processes when Lighthouse launches:

{
  id: 'api',
  autoStart: true,
  mode: 'auto',  // or 'managed'
  // ...
  healthCheck: {
    url: 'http://localhost:4005/health',
    interval: 5000,
  },
}

Environment Variables

Pass environment variables to processes:

{
  id: 'api',
  // ...
  env: {
    NODE_ENV: 'development',
    DATABASE_URL: 'postgresql://localhost:5432/dev',
    LOG_LEVEL: 'debug',
  },
  healthCheck: {
    url: 'http://localhost:4005/health',
    interval: 5000,
  },
}

Working Directory

Specify the working directory for the process:

{
  id: 'api',
  cwd: './services/api',  // Relative to project root
  // or
  cwd: '/absolute/path/to/service',
  // ...
  healthCheck: {
    url: 'http://localhost:4005/health',
    interval: 5000,
  },
}

Multiple Instances

Run multiple instances of similar services:

processes: [
  {
    id: 'api-1',
    name: 'API Server 1',
    command: 'pnpm',
    args: ['dev'],
    cwd: './api',
    mode: 'auto',
    env: { PORT: '4005' },
    healthCheck: {
      url: 'http://localhost:4005/health',
      interval: 5000,
    },
  },
  {
    id: 'api-2',
    name: 'API Server 2',
    command: 'pnpm',
    args: ['dev'],
    cwd: './api',
    mode: 'auto',
    env: { PORT: '4006' },
    healthCheck: {
      url: 'http://localhost:4006/health',
      interval: 5000,
    },
  },
]

Next Steps

• Bruno Integration - API testing
• Keyboard Shortcuts - All shortcuts