Getting Started

Install LaunchPad, discover your existing agents, and create your first scheduled job in under 60 seconds.

What is LaunchPad?

LaunchPad is a local macOS dashboard for managing launchd LaunchAgents -- the system-level scheduler that powers all background automation on macOS. Instead of hand-writing XML plist files and memorizing launchctl subcommands, LaunchPad provides a modern, visual interface for creating, monitoring, and controlling every scheduled and event-driven job on your Mac.

The application runs entirely on your machine. There are no cloud services, no accounts, no network exposure. All data stays on your Mac in a local SQLite database. The dashboard auto-starts on login and lives in your menubar for instant access.

System Requirements

LaunchPad uses Touch ID via WebAuthn for confirming destructive operations. Machines without Touch ID fall back to password prompts via the macOS LocalAuthentication framework.

Installation

Option 1: Homebrew (recommended)

The fastest way to install LaunchPad. Homebrew handles Node.js dependencies and sets up the auto-start LaunchAgent automatically.

brew tap launchpad-app/tap
brew install launchpad

After installation, LaunchPad starts automatically and opens in your default browser at http://localhost:24680.

Option 2: Manual Installation

Clone the repository and install dependencies manually. This approach is ideal for development or customization.

# Clone the repository
git clone https://github.com/launchpad-app/launchpad.git
cd launchpad

# Install dependencies with pnpm
pnpm install

# Create the SQLite database and run migrations
pnpm db:push

# Build for production
pnpm build

# Start the server (port 24680)
pnpm start

# Optional: Install auto-start LaunchAgent
pnpm setup:autostart

First Launch

When you open LaunchPad for the first time, it performs an automatic discovery scan across your system.

What happens during discovery

1. Scans ~/Library/LaunchAgents/ -- finds all your user-level LaunchAgent plist files
2. Scans /Library/LaunchAgents/ -- finds system-wide agents (displayed as read-only)
3. Parses each plist -- extracts label, command, schedule, environment variables, log paths, and all configuration keys
4. Cross-references launchctl list -- determines whether each job is loaded or unloaded, running or idle, and captures the last exit code
5. Syncs to the database -- stores everything in the local SQLite database for fast querying

Jobs not created by LaunchPad are marked as "External" and are read-only. You can view their configuration and logs, but you cannot edit or delete them through the dashboard. This protects system agents from accidental modification.

The full discovery scan completes in under 3 seconds, even with 100+ plists.

Quick Start: Your First Agent

Let's create a simple LaunchAgent that runs a backup script every weekday at 9 AM.

Step 1: Open the Job Builder

Click the "New Job" button in the dashboard header, or press Cmd+N. The Job Builder form opens with sensible defaults pre-filled.

Step 2: Configure the basics

Step 3: Set the schedule

LaunchPad provides three interchangeable schedule input methods. Use whichever feels natural:

0 9 * * 1-5

every weekday at 9am

Step 4: Preview and save

Before saving, expand the plist preview pane to see the generated XML. This is the exact file LaunchPad will write to ~/Library/LaunchAgents/:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.launchpad.daily-backup</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/scripts/backup.sh</string>
    <string>-v</string>
    <string>--incremental</string>
  </array>

  <key>WorkingDirectory</key>
  <string>/Users/you/scripts</string>

  <key>StartCalendarInterval</key>
  <array>
    <dict>
      <key>Hour</key><integer>9</integer>
      <key>Minute</key><integer>0</integer>
      <key>Weekday</key><integer>1</integer>
    </dict>
    <dict>
      <key>Hour</key><integer>9</integer>
      <key>Minute</key><integer>0</integer>
      <key>Weekday</key><integer>2</integer>
    </dict>
    <!-- ... Wed, Thu, Fri -->
  </array>

  <key>StandardOutPath</key>
  <string>/Users/you/Library/Logs/LaunchPad/com.launchpad.daily-backup.log</string>

  <key>StandardErrorPath</key>
  <string>/Users/you/Library/Logs/LaunchPad/com.launchpad.daily-backup.err</string>

  <key>LaunchPadManaged</key>
  <true/>
</dict>
</plist>

Click "Save & Activate". LaunchPad writes the plist file, validates it with plutil -lint, and registers it with launchctl bootstrap. Your job is now live.

Tech Stack

LaunchPad is built as a localhost monolith -- a single Next.js process serving both the UI and API routes, with SQLite as the sole persistence layer.

Port 24680 was chosen to avoid conflicts with common development servers (3000, 5173, 8080). The server binds exclusively to 127.0.0.1, making it inaccessible from the network.

Project Structure

launchpad/
  app/                    # Next.js App Router pages and layouts
    api/                  # API route handlers (/api/jobs, /api/discover, etc.)
    (dashboard)/          # Dashboard pages (job list, detail, create)
    settings/             # Settings page
  lib/                    # Service layer
    discovery.ts          # Filesystem scanning and plist parsing
    plist-engine.ts       # Plist XML generation and validation
    schedule-translator.ts # Visual/cron/NLP to launchd schedule conversion
    launchctl.ts          # Type-safe launchctl command wrapper
    log-capture.ts        # Background log polling and storage
    notifications.ts      # macOS Notification Center integration
  db/                     # Drizzle ORM schema and migrations
  components/             # React UI components (shadcn/ui based)
  menubar/                # Menubar tray process
  ~/.launchpad/
    launchpad.db          # SQLite database
  ~/Library/Logs/LaunchPad/
    *.log, *.err          # Job stdout/stderr log files

Next Steps

Now that you have LaunchPad installed and running, explore what it can do:

• Feature Guide -- Deep dive into agent discovery, the job builder, scheduling, event triggers, log viewer, and more
• API Reference -- Full endpoint documentation for integrating with LaunchPad programmatically
• Architecture -- Understand the system design, data flows, and security model
• Troubleshooting -- Common issues, error messages, and launchd-specific gotchas