Getting started

devkit wraps the Docker Compose stack you already use and serves your Laravel folders next to it. Everything below works from the CLI. The desktop apps run the same commands for you.

1. Add your stack

devkit stack add ~/Project/webpress/webpress-infra/webpress-super-app-local-development
devkit stack list

devkit reads docker compose config and recognizes the database (MySQL or MariaDB), Redis, Caddy, PHP-FPM, S3 and mail services by their images.

2. Park your sites

devkit park ~/Project/webpress/sites   # every Laravel folder inside is a site
devkit link ~/work/one-off-site        # or add a single folder
devkit site list

3. Start a site

devkit template get core-development   # the .env template, seeded from your current .env
devkit site up core-development        # http://localhost:8100 and its queue worker
devkit proc list core-development      # queue, schedule, vite…
devkit exec core-development -- php artisan about
devkit doctor core-development
devkit site down core-development

The .env is rendered from the template on every start. The original is kept in ~/.config/devkit/backups/<site>/env.orig.

4. Work in parallel with lanes

devkit lane new core-development crm-fix   # worktree on feat/crm-fix, database core_development_l1
devkit lane up core-development--crm-fix
devkit db snapshot core-development--crm-fix before-migrate
devkit db restore core-development--crm-fix before-migrate --yes
devkit lane rm core-development--crm-fix   # refuses while work is uncommitted or unpushed

5. HTTPS with Caddy (optional)

devkit trust                                    # once: trust mkcert's local CA (asks for your password)
devkit site set core-development --engine caddy --php 8.3
devkit site up core-development                 # https://core-development.localhost
devkit xdebug on core-development

This needs a stack with a Caddy and a PHP-FPM service.

6. Connect an AI agent

devkit mcp config claude-code      # prints the line to paste
devkit mcp config cursor --write   # or merges the entry into the project's config
devkit mcp audit                   # what agents did, newest first

Agents get the same operations as tools. Tools that delete or overwrite something need "confirm": true, and every call is written to ~/.config/devkit/audit.log on your machine.

The desktop apps

macOS: devkit.app lives in the menu bar. Choose Open devkit… for the manager window with Sites, Lanes, Stacks, Templates, PHP, Settings and MCP.
Linux: devkit-gtk shows a tray item, or a small window where no tray is available, and a manager window with your sites and their details.

Where devkit keeps things

~/.config/devkit/: settings, site list, .env backups, logs, certificates and the MCP audit log. It follows XDG_CONFIG_HOME.
~/Library/Logs/devkit/devkit-app.log (macOS) and ~/.local/state/devkit/devkit-app.log (Linux): what the app ran.

Uninstall

Quit the app, then delete /Applications/devkit.app (macOS) or ~/.local/lib/devkit-app and the links in ~/.local/bin (Linux). Delete ~/.config/devkit to remove devkit's settings. Your sites, stacks and databases are left as they are.