Getting started

This guide starts from an existing project, for example a Vite or Laravel app in ~/Code/myproject. No project at hand? Create one from a template.

1. Add the project

   Drag the folder onto the Joppa window, or click Add a project (shortcut N) and pick it.

   Joppa reads the folder (package.json scripts, workspaces, artisan, Docker Compose) and suggests a domain for each dev server it finds:

   myproject.test        → :5173   vite
   api.myproject.test    → :8000   laravel

   Adjust the subdomains or ports if needed, then confirm. See Add a project.

2. Start the dev server

   Start it as usual in your terminal (bun dev, php artisan serve…), or let Joppa handle it: Processes tab (P) › Analyze the project, then Save and start. See Processes.

3. Open https://

   Press O on the project page: https://myproject.test opens, with the padlock.

4. Plug in a database

   In Services, add PostgreSQL (or MySQL, MariaDB) and start it. Then, in the project’s Environment tab (E), click Use PostgreSQL: Joppa creates the project’s database and shows the .env diff before writing it.

5. Take the keyboard

   ⌘ K opens the palette: type “open”, “copy”, “start”… Every action in the app is there. See Keyboard shortcuts.

What’s next

• Concepts: how the pieces fit together.
• The joppa command: the same thing from the terminal.
• MCP server: let Claude or Cursor start your services.