README

Zero-config local development for Linux.
Nginx + DnsMasq, every project at *.test, ~7 MB of RAM.
No Vagrant, no Docker, no /etc/hosts edits.

Quick start · Features · Command reference · Dashboard · Changelog

Why Valet Linux+

Valet configures Nginx to start with your machine and uses DnsMasq to resolve every *.test domain to your local sites — linked directories, parked folders, even proxies to other ports. You get HTTPS with one command, per-site PHP versions, and a browser dashboard that can actually change things — all without a VM.

This fork extends the upstream Valet Linux+ with a controllable dashboard, project bootstrapping, diagnostics, database tooling, idle sleep, and more. See What's Different vs Upstream.

Features

Serve

Capability	What you get
Link & park	`valet link` a single project or `valet park` a whole code directory
Proxy	`valet proxy api.test http://127.0.0.1:3000` for Node, Docker, or anything else
HTTPS	`valet secure` / `valet unsecure`, `valet trust`, `cert:list` / `cert:renew`
PHP isolation	`valet isolate 8.3`, `valet use 8.4`, `valet which-php` — any PHP `>=7.0`
Node via nvm	`valet node:use`, `node:install`, `node:current` — reads `.nvmrc`
Idle sleep	`valet sleep` / `valet wake` — stops isolated FPM pools when nothing needs them

Dashboard

valet dashboard serves a web UI at http://valet.<domain>:

Read-only from anywhere — sites, services, health, logs, certificates, caches, databases, snapshots. Safe to expose over ngrok.
Mutations only from your machine — over POST from loopback, with CSRF (double-submit cookie + header), same-origin check, and a confirmation that echoes the exact value being destroyed. Every action is appended to ~/.config/valet/Log/dashboard-audit.log.
Privileged work is opt-in — sudo valet dashboard:privileges install drops a root-owned helper at /usr/local/libexec/valet-dashboard-helper with a NOPASSWD sudoers rule pinned to that exact path. Without it, the dashboard stays read-only and says so. The helper never executes user-supplied shell text; it re-validates every command against an allowlist.
Background jobs — imports, exports, snapshots, and backups run detached and are polled so php-fpm timeouts don't kill them.

See docs/dashboard.md for the full security model and docs/api-v1.md for the machine API.

Databases

MySQL / MariaDB — valet db:list|create|drop|reset|import|export|setup|refresh, plus SQLite (db:sqlite, db:sqlite:reset), direct URLs (db:url, db:open) and always-on Adminer at https://database.valet.<domain> with a pluggable ~/.config/valet/database/plugins directory.
PostgreSQL (opt-in) — valet install --with-pgsql enables a matching pg:* family.

Addons & object storage

MinIO (S3-compatible) via Valet — valet addon:enable minio wires the binary at /usr/local/bin/minio as a Valet service (cli/Valet/ServiceRegistry.php:50 template, cli/Valet/Addon.php:18 catalog). It creates the proxy https://minio.test (~/.config/valet/Nginx/minio.test → http://127.0.0.1:9000), config.json:services.minio, and on Ubuntu 26.04 where no minio apt package exists it falls back to a direct download from dl.min.io and creates /etc/systemd/system/minio.service (ExecStart=/usr/local/bin/minio server --license $MINIO_LICENSE $MINIO_OPTS $MINIO_VOLUMES, EnvironmentFile=/etc/default/minio, user minio-user, data /mnt/data). valet status (ServiceRegistry.php:300 resilient to missing unit) then shows minio | installed/enabled/active, and valet start|stop|restart minio delegate to systemctl. Console is http://127.0.0.1:9001 (MINIO_OPTS --console-address :9001). Creds minioadmin/minioadmin in /etc/default/minio, license via MINIO_LICENSE=/etc/minio/license or mc license update local ~/Downloads/minio.license (mc license --help).

Valet vs standalone: standalone you do the same manually — curl dl.min.io... | install, groupadd/useradd, mkdir /mnt/data, write /etc/default/minio + minio.service (--license), daemon-reload; enable --now, write an Nginx server block + cert. Valet automates it, integrates with valet status/restart/proxy/domain, and on 26.04 AbstractPackageManager.php:74 detects /usr/local/bin/minio so installed:true without apt.
```
R2_BUCKET=zamil-ac-dev
R2_ACCESS_KEY_ID=minioadmin
R2_SECRET_ACCESS_KEY=minioadmin
R2_ENDPOINT=https://minio.test
R2_PUBLIC_URL=https://minio.test/zamil-ac-dev
# direct: R2_ENDPOINT=http://127.0.0.1:9000
```
Create bucket once: mc alias set local http://127.0.0.1:9000 minioadmin minioadmin && mc mb local/zamil-ac-dev --ignore-existing or via console http://127.0.0.1:9001.
Meilisearch — valet addon:enable meilisearch (ServiceRegistry.php:77 template port 7700) same pattern: fallback download from GitHub + systemd unit at /etc/systemd/system/meilisearch.service.

Project DX

valet clone <repo> [--link --init --secure --isolate=8.3 --open] — clone and bootstrap in one shot
valet init [--db --migrate --composer --isolate --secure] — wire .env, create the DB, install deps, migrate
valet tinker / valet repl — framework REPL with the site's PHP binary
valet env [--json --export=shell --print-db-url --php-bin] — merged project + Valet env vars
valet shell-hook — eval "$(valet shell-hook)" in your .zshrc to auto-switch PHP on cd
valet tune [dev|fast|debug] / valet bench [site] — FPM presets and TTFB measurement
valet cache:status|clear|doctor — Composer / npm / Valet cache awareness
valet snapshot:create|list|restore|delete, valet backup / valet restore, valet profile:save|use|list

Diagnostics & repair

valet diagnose [--json] — one-shot health report (OS, PHP, Nginx, DNS, services, paths)
valet doctor [--fix --dry-run --json] — diagnose and optionally repair
valet health / valet log / valet logs / valet mail / valet status
valet xdebug on|off|status

Requirements

Requirement	Notes
PHP	`>=8.2` on the CLI. Any `>=8.2` is accepted for `valet use`; isolation supports `>=7.0`. Extensions: `pdo`, `posix`, `json`, `mbstring`, `xml`.
Nginx & DnsMasq	Installed and configured automatically.
Composer	For the initial install (`composer global require`).
OS	Debian/Ubuntu, Fedora, and Arch-based distros (distro-aware services).
Optional	MySQL/MariaDB (default DB), Redis, Mailpit (mail catching), Ngrok (sharing), PostgreSQL (`--with-pgsql`).

Quick Start

# Install
composer global require ahmdadl/valet-linux-plus
valet install

# Options
valet install --with-pgsql   # also set up PostgreSQL
valet install --mariadb      # use MariaDB instead of MySQL

# Serve something
cd ~/Code/my-app
valet link                    # → http://my-app.test
valet secure                  # → https://my-app.test
valet isolate 8.3             # pin this site to PHP 8.3

# Or park a whole directory
valet park ~/Code             # every subfolder becomes *.test

# Dashboard
valet dashboard --open        # browser UI at http://valet.test

Add auto-switching PHP on cd:

echo 'eval "$(valet shell-hook)"' >> ~/.zshrc

Full option list for every command: docs/commands.md.

Command Overview

Category	Commands
Service lifecycle	`install`, `start`, `restart`, `stop`, `uninstall`, `status`, `services`, `service:add`, `service:remove`
Version & update	`is-latest`, `update`
Domain, port & net	`domain`, `port`, `which`, `proxy`, `unproxy`, `proxies`
Paths & linking	`park`, `paths`, `forget`, `link`, `unlink`, `links`, `secure`, `unsecure`, `secured`, `trust`, `cert:list`, `cert:info`, `cert:renew`
Sleep & idle	`sleep`, `wake`, `idle`
Database (MySQL)	`db:list`, `db:create`, `db:drop`, `db:reset`, `db:setup`, `db:refresh`, `db:sqlite`, `db:sqlite:reset`, `db:import`, `db:export`, `db:configure`, `db:url`, `db:open`, `database`
PostgreSQL	`pg:list`, `pg:create`, `pg:drop`, `pg:reset`, `pg:import`, `pg:export`, `pg:configure`
PHP & Node	`use`, `isolate`, `unisolate`, `isolated`, `which-php`, `php`, `composer`, `node:current`, `node:install`, `node:use`, `tinker`, `repl`, `shell-hook`, `tune`, `bench`
Project	`clone`, `init`, `env`, `profile:`, `snapshot:`, `cache:`, `addon:`, `api`
IDE helpers	`code`, `ps`, `subl`, `open`
Sharing	`share`, `fetch-share-url`, `ngrok-auth`
Diagnostics	`diagnose`, `doctor`, `health`, `xdebug`, `log`, `logs`, `mail`, `dashboard`, `dashboard:privileges`, `backup`, `restore`

What's Different vs Upstream

Based on valet-linux-plus/valet-linux-plus. Everything below is new in this fork:

Controllable dashboard — tabbed UI for sites, databases, PHP & Node, backups & certificates, logs & diagnostics, and settings, with 55 curated actions behind one POST /api/actions/<slug> endpoint. Read-only from anywhere; mutations only from the local machine through an opt-in root helper and an audit log.
Idle sleep — per-site sleep/wake plus an idle timer and pool-RAM reporting so isolated FPM pools don't burn RAM when nothing needs them.
Real version discovery — the dashboard and CLI show PHP and Node versions that are actually installed, not a fixed range.
Project DX — clone, init, tinker/repl, db:sqlite, cache:*, shell-hook, tune, bench, snapshot:*.
Databases — always-on Adminer with plugins, db:url/db:open, full pg:* family.
Profiles, env & API — profile:*, valet env, and a machine-readable valet api (v1).
Diagnostics — diagnose/doctor/health, xdebug toggle, log tailing, Mailpit launcher, custom services (service:add / service:remove with templates).
Hardening — command-injection and SQL-injection fixes, PackageManager/ServiceManager abstractions, hardened server.php, PHPStan level 9.

Changelog

See CHANGELOG.md.

Credits

A community fork of genesisweb/valet-linux-plus (now valet-linux-plus/valet-linux-plus) by Uttam Rabadiya and Divyank Munjapara. All credit for the original base goes to them — this fork maintains and extends their work. Not affiliated with or endorsed by the original authors.

License

MIT — see LICENSE.md.

ahmdadl / valet-linux-plus

Package info

Security

Statistics