Everything you can do with Dunebox.

Installation & first run

Dunebox is a single portable folder — no installer, no Windows service. You download a zip, extract it, and open dunebox.exe once. On first launch a short wizard collects your preferences, then Dunebox downloads the components you picked and configures them for you.

1. Download the latest dunebox-vX.Y.Z.zip from the Releases page.
2. Extract it — we recommend C:\dunebox, but any folder, drive or USB stick works. That folder becomes Dunebox's home.
3. Open dunebox.exe and follow the setup wizard (below).
4. Dunebox downloads the selected components and writes all configuration. You'll get one Windows confirmation (UAC) — it covers adding the host entries and trusting the local certificate, both in a single elevation.

The setup wizard, step by step

The first download is the largest part — expect roughly 2–3 GB depending on what you selected, and an internet connection on first launch. After that, Dunebox runs fully offline.

The Dunebox app

The Dashboard is your control center. Each service — the web server, every PHP version, your databases, Redis, Mailpit and the scheduler — appears as a row showing whether it's running, and you start or stop everything with one switch. The same control lives in the tray.

• Start / stop — turn the whole environment on or off; only the components you enabled are launched.
• Tray & close-to-tray — closing the window keeps services running in the background; quit from the tray to stop everything cleanly. A Windows shutdown or sign-out stops services gracefully too.
• Autostart — optionally launch Dunebox when you sign in to Windows (toggle in Settings).
• Tabs — Dashboard, Hosts, Cron Jobs, DNS and Settings cover everything in this guide.

Hosts & local sites

A host is a local site, e.g. myapp.test. Add one from the Hosts tab and Dunebox does the rest: it writes the web-server configuration, adds the name to your Windows hosts file (or to DNS), and adds it to the trusted certificate so HTTPS works immediately.

What you set per host

Edit or remove a host anytime from the Hosts tab; Dunebox updates the configuration, hosts file and certificate accordingly (changes that touch the system ask for one confirmation). New host configuration takes effect when services restart.

Project mode

A site can keep its settings inside the project, in a small .dunebox/config.json file. That file holds the hostname, PHP version, HTTPS, engine, database instance and any per-project Cron Jobs — and it travels with your git repository. When a teammate clones the repo, Dunebox finds the file during its folder scan and recreates the exact same site automatically. No shared README of "set PHP to 8.2, point the docroot here" — it just works.

Example .dunebox/config.json

{
  "hostname": "myapp.test",
  "docroot":  "public",
  "php":      "8.3",
  "ssl":      true,
  "engine":   "apache",
  "cron":     ["@daily php artisan backup:run"]
}

Commit .dunebox/config.json to git; the .dunebox/logs/ folder is ignored automatically. Editing the site from the Hosts tab keeps this file as the source of truth.

PHP versions

PHP 5.6 · 7.4 · 8.2 · 8.3 · 8.5 run side by side. Each site picks its own version, and the web server routes each request to the right one — so you can keep a legacy app on 5.6 and a modern one on 8.3 at the same time, on the same machine. The default version (8.2 out of the box) is used for new sites and the command line, and you can change it in Settings.

In the terminal, php, artisan and composer automatically use the PHP version of the project you're in — no manual switching, no aliases. Outside a project they use the default version.

The modern versions ship with the extensions real projects need, ready to use: Imagick, GD, the MongoDB driver, Redis, intl, OPcache, mbstring, cURL, and PDO for MySQL, PostgreSQL and SQLite. Redis-backed cache, sessions and queues work out of the box — no manual extension setup.

Databases

Run several engines at once — and even several versions of the same engine — each on its own port and its own data directory. MySQL 9.6, Redis and Mailpit are on out of the box; the rest are one toggle away in Settings. You can change any database port from Settings (Apply, then restart services).

Default credentials (host 127.0.0.1): user dunebox / password secret with full privileges (recommended), plus the engine's superuser — root for MySQL/MariaDB, postgres for PostgreSQL — also with password secret. MongoDB and Redis run without authentication, bound to localhost only. The exact connection details for every active engine are always shown in Settings → the package info popups.

Example Laravel .env — MySQL

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306        # 3307 = 8.0, 3308 = 5.7, 3309 = MariaDB, 5432 = PostgreSQL
DB_DATABASE=your_db
DB_USERNAME=dunebox
DB_PASSWORD=secret

Tuned for development

MySQL and MariaDB ship with settings chosen for a development machine rather than a server: a larger data cache, commits flushed once per second instead of on every write, and no binary log. Expect noticeably quicker imports, migrations and queue processing than a stock install. The trade-off is that a power cut or crash can cost the last second of writes — the right call locally, and a reason not to reuse these settings on a production server.

Queries slower than one second are recorded in logs/<instance>-slow.log — the first place to look when a local site feels sluggish. If you work with a large database, raise innodb_buffer_pool_size in the engine's .ini under config/mysql/ (your edits there are never overwritten) and restart services.

Web tools & email

Each tool is also reachable over HTTPS (https://…localhost) with the same trusted certificate, and Mailpit's interface is available directly on http://localhost:8025.

Email never leaves your machine. Mailpit captures everything your apps send. PHP's mailer is already wired to it, so mail() and frameworks just work with no extra setup. To use SMTP explicitly: host 127.0.0.1, port 1025, no auth, no encryption.

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="hello@example.test"

HTTPS & certificates

Dunebox runs its own local certificate authority — the Dunebox Local CA — and trusts it on your machine during setup. Every site and web tool gets a real, valid certificate, so you see the green padlock on https://myapp.test with no browser warnings. When you add or edit a host, its name is added to the certificate automatically.

If a browser ever shows a warning — for instance after a fresh Windows profile — the Dashboard detects that the CA isn't trusted and offers a one-click "Trust the certificate" button (it asks for one Windows confirmation).

Chrome, Edge and other Chromium browsers trust the certificate immediately. Firefox is covered through Windows' enterprise-roots setting, so it works too.

Cron Jobs

Schedule recurring commands from the Cron Jobs tab with a guided editor — pick a schedule and a command; there's no crontab syntax to memorize. Each job runs with the right PHP version, and jobs only run while Dunebox is on.

• Global jobs belong to the Dunebox instance and run on the default PHP.
• Per-project jobs live inside the project's .dunebox file, run with that project's PHP, and travel with the repo in git — so teammates inherit the same schedule (a Laravel schedule:run, a nightly backup, etc.).

Output goes to log files in your logs folder. Jobs are read when services start, so after adding or changing a job, restart services for it to take effect. You can also run a job once on demand to test it. List jobs from the terminal with dunebox cron list.

Windows shell. Jobs run through the Windows command shell, so a command written for a Unix/Linux environment — calling bash or Unix-only tools, using Linux-style chaining or hard-coded / paths — may behave differently or fail. Prefer Laravel's php artisan schedule:run and PHP-level scheduling, which are portable; see the Compatibility note.

Local DNS (optional)

By default Dunebox manages the names you add through the Windows hosts file — simple and reliable. If you'd rather not edit the hosts file at all, enable Local DNS from the DNS tab: Dunebox then answers wildcard names like *.test automatically, so any name.test resolves to your machine without a hosts entry.

It's off by default. Turning it on routes the chosen suffixes to Dunebox's local resolver (one Windows confirmation); turning it off restores the classic hosts-file behaviour.

Use a suffix that isn't a real internet domain (e.g. .test or .localhost), never a real top-level domain like .io or .com: the routing rule applies to the whole suffix, so it would also capture real websites under it. If you remove or change a suffix, don't forget to apply the change to the system again (same confirmation) — until you do, the previous routing rule stays active.

Developer tools

From Settings → Developer tools you can install and update the everyday tools that live alongside PHP: Git, Node.js, nvm, Python (2 and 3) and FFmpeg. These come from their official sources via Windows' own package manager (winget) and are installed normally on your system — Dunebox just gives you one place to manage them and shows when an update is available.

Composer is different: it's bundled inside Dunebox and always runs on the correct PHP version for the project you're in, so composer install never picks the wrong PHP.

Terminal & commands

If you enabled terminal integration during setup, open any PowerShell or Command Prompt and type dunebox to prepare the session. From then on, the everyday commands are context-aware:

# inside a project served by Dunebox
php -v            # the project's PHP version
artisan migrate   # run with the project's PHP
composer install  # always the right PHP
mysql -u dunebox -p  # the project's database instance

php, artisan, composer and mysql all detect the project you're standing in and use the right PHP version — and the right database instance — for it, automatically. Run dunebox followed by a command (e.g. dunebox up) for the management commands below.

Need a specific version regardless of the folder? Each installed version also has its own direct command: php82, php74, … for PHP, and mysql96, mysql57, mariadb12, postgres18 (plus the matching mysqldump96, pg_dump18, …) for databases — they connect to that exact version on its own port.

CLI reference

Everything in the app is also available from the command line. The most useful commands:

Settings

Everything the wizard asked, plus more, lives in Settings and can be changed anytime. Changes that affect configuration take effect after a service restart.

A Connections & Email reference is always at hand too: connection details for every active database, plus ready-to-paste SMTP settings for Mailpit and the link to its inbox.

Claude integration

From the wizard or Settings → Claude integration, connect Dunebox to Claude Code or Claude Desktop (Dunebox detects which are installed). Once connected, you can ask Claude to work with your local environment in plain language — it talks to Dunebox directly.

From either client, Claude can:

• list your sites, packages and Cron Jobs, and check which services are running;
• read the tail of any log file to help diagnose a problem;
• create or remove a site, and change a site's PHP version;
• add, enable/disable, remove or run Cron Jobs.

In Claude Code, which also has terminal access, Claude can additionally run artisan and composer on the project's PHP through the context-aware shims.

Restart the Claude app after connecting for it to take effect.

Moving Dunebox

Because everything lives in one folder, you can move or rename it — to another drive, a different path, or a USB stick. On the next launch Dunebox notices the new location, re-writes its configuration to match, and updates the related system entries (PATH and autostart) automatically. Your sites, databases and settings come along.

Compatibility

Uninstall

There's no installer and no Windows service, so removal is mostly "quit and delete the folder". For a completely spotless cleanup, undo the few per-user changes Dunebox makes first:

1. Quit Dunebox from the tray so all services stop.
2. In Settings, turn off autostart and terminal integration — this removes its startup entry and its PATH entry.
3. If you used Local DNS, disable it (this removes the DNS routing rules); then your hosts file is clean too.
4. Delete the Dunebox folder (e.g. C:\dunebox) — and the separate data folder as well if you don't need the databases.
5. Optional: remove any leftover *.test lines from the Windows hosts file, and remove the Dunebox Local CA from the certificate store if you no longer want to trust it.