Zapper

A lightweight dev environment runner for local multi-service projects.

Install

npm install -g @mp-lb/zapper

On Windows, run Zapper from WSL2. Use Linux paths in zap.yaml, and make sure Docker is reachable from that WSL distro before starting Docker services.

Create zap.yaml

project: myapp
env: [.env]

native:
  backend:
    cmd: pnpm dev
    env: "*"

  frontend:
    cmd: pnpm dev
    cwd: ./frontend
    env: "*"

docker:
  postgres:
    image: postgres:15
    ports:
      - 5432:5432

Run

zap up
zap status
zap down

Add Tasks

Use tasks for one-off project commands that should share the same local environment.

tasks:
  seed:
    preconditions:
      - test -n "$DATABASE_URL"
    cmds:
      - pnpm db:seed

  console:
    interactive: true
    silent: true
    cmds:
      - psql "$DATABASE_URL"

zap task seed
zap task console

Deploy

The same zap.yaml can deploy to the cloud: add an opt-in deploy: block and run zap arc deploy — your services, on your own cloud accounts. See Deploy (Zap Arc).

For full reference docs, see Commands, Configuration, Services, and Tasks.

Run zap profile to pick a profile with the arrow keys and Enter. Zapper stops excluded services, starts required services, and exits when the switch completes. Use zap profile get and zap profile set <name> in scripts.

For profile-based env files, service selection, and isolated stacks, see Profiles.

For readiness waits and dependency startup behavior, see Health Checks.

For packaging and local machine runtime plans, see Local Runtime Compatibility.

For the command result and rendering contract, see Command Output.

For CLI development, testing, and release workflow, see CLI Development in the repo.

For the local menu bar app development loop, see macOS Development in the repo.