Download the PHP package ldiebold/isolate without Composer

Isolate for Laravel

Run many checkouts of the same Laravel app side by side without them stepping on each other.

When you run the same app from several git worktrees or working copies at once, every copy fights over the same runtime footprint: they all try to php artisan serve on port 8000, share one database, and write to the same Redis / queue / cache prefixes. You get "address already in use" errors and copies clobbering each other's data.

This collides hard with AI coding agents. A common workflow now is to fan several agents out in parallel — each on its own git worktree or workspace — so they can build, boot, and test independently. Without isolation they all grab port 8000 and the same database and trip over one another.

php artisan isolate fixes this with one idempotent command per worktree. It picks a free instance number n and derives the whole runtime footprint from it — ports (base + n), the database name, and Redis / Horizon prefixes (base + suffix(n)) — verifies nothing is already in use, writes the app's .env, and creates the per-instance database. Point each agent at its own checkout, run isolate once, and every agent gets a clean, isolated environment:

(The Database and Prefix columns share a base here for illustration. In practice the database name derives from your default connection's configured database and the prefixes from isolate.name, so their bases can differ.)

At n = 0 no suffix is added, so a checkout returns to vanilla defaults. Everything is idempotent and lock-guarded, and every seam is an interface you can swap.

Installation

Requires PHP 8.2+ and Laravel 11, 12, or 13.

The service provider is auto-discovered. A typical worktree / agent setup runs isolate right after creating the checkout:

Publish the config if you want to customise the resource map:

Documentation

Commands

Inspect the current state and candidate numbers:

Tear down per-instance resources (the inverse of isolation): drops the database(s) and flushes the Redis keyspace(s):

isolate:teardown drops the per-instance database(s) and flushes every key under the instance's keyspace prefixes (REDIS_PREFIX, HORIZON_PREFIX) across all configured Redis connections — pass --keep-redis to leave Redis alone. It never rewrites .env — except when you tear down the active instance with --force, where it then resets .env to vanilla so the app is not left pointing at dropped resources (pass --keep-env to opt out). It refuses to drop vanilla (instance 0) and refuses the active instance unless you name it explicitly with --force; under --all the active instance is always protected. A missing database is reported rather than treated as an error and an empty keyspace is simply "nothing to flush", so re-runs are idempotent; a failed drop or an unreachable Redis degrades to a warning and the command still succeeds. To clean up other coupled resources, use the afterDatabaseDropped / afterPrefixFlushed hooks (below).

Running isolate with no flags behaves like --auto. Re-running is idempotent: a recorded ISOLATE_NUMBER is preferred, so the same checkout keeps its number, existing databases are reused, and the resolved .env values stay stable — exactly what you want when an agent re-runs its setup script.

How it works

Every resource derives its value from one shared instance number n:

Redis/Horizon prefixes are marked as keyspaces ('keyspace' => 'redis'), which fixed-width zero-pads their suffix (instance 7 → …07) so one instance's keys can never be matched by a scan for another (7 vs 70), and flags them to be flushed on isolate:teardown.

At n = 0 no suffix is added, so names return to their base values. Fresh auto-selection only chooses a number whose browser-facing ports avoid Chrome's restricted-port set and whose actual resources (ports, databases, Redis prefixes) are free. Explicit --number choices and a recorded ISOLATE_NUMBER are treated as intentional self-claims: they may warn about detected conflicts, but restricted-port filtering is not applied to them. There is no sibling-checkout discovery; conflicts are detected from real resource state.

Configuration

config/isolate.php is pure, cacheable data:

Each resource declares an active_when predicate so the default map self-activates only what is present: 'always', ['env' => 'KEY'], ['config' => 'path'], ['package' => 'vendor/name'], ['any' => [...]], ['all' => [...]]. The {default} token in a config path resolves to the default database connection.

Band spacing (read this before customising the map)

Because the same n is added to every port base, distinct bases never collide within one instance. band_size exists to stop cross-instance overlap (baseA + nₐ == baseB + n_b). The invariant validated on every run is:

port bases must be at least band_size apart and ≥ 1024 (unprivileged), and max_instances must be ≤ band_size.

max_instances is a count, so valid numbers are 0 .. max_instances - 1.

Vanilla Laravel's serve (8000) and Reverb (8080) are only 80 apart and would fail validation at band_size = 100. The shipped map therefore spaces Reverb at 8100. If you add resources, keep their bases ≥ band_size apart (or lower band_size).

Worktree file hydration

A fresh git worktree add only checks out tracked files, so the gitignored artifacts an app needs to run — node_modules, and often a real .env — are missing. When isolate runs inside a linked worktree it copies them from the origin (the main worktree it was created from), so you skip a reinstall:

• Copy-if-missing. Existing paths are never overwritten, so re-runs are no-ops and anything already placed by your tooling is left alone.
• Runs before .env is written. A copied .env keeps the origin's real values and isolate layers the per-instance ports/prefixes on top — real secrets and an isolated footprint.
• Only inside a linked worktree. In the main repo or a plain clone it does nothing. Missing origin paths are skipped silently; a failed copy degrades to a warning and never fails the run.
• Paths are literal and repo-root-relative (files or directories); entries that are absolute or escape the project with .. are refused. The native cp/robocopy is used for speed with a portable PHP fallback (Linux, macOS, Windows).

Set 'copy' => [] to disable it, or pass --no-copy for a one-off skip.

vendor is intentionally not in the list. isolate is php artisan, which cannot boot without vendor/autoload.php, so vendor must already exist by the time it runs — copy-if-missing would only ever skip it. Install it from your worktree-creation step instead:

If your worktrees are created by a tool (an "on workspace created" hook), put composer install there before isolate. composer install is also correct — it matches this worktree's own composer.lock. If you would rather copy vendor to save the install time, do it in that same hook (cp -a ../origin/vendor vendor), understanding the trade-off: a copied vendor/node_modules is stale if the branch changed its lockfile, and assumes the same machine/platform.

Extending

Config stays pure data; anything involving closures or runtime objects is registered on the Isolate facade, typically from a service provider's boot():

For deeper customisation you can register a custom applier or collision detector, or override a raw resource definition:

Most seams are interfaces with shipped defaults and test fakes: PortChecker, EnvWriter, and PackageDetector are resolved from the container and can be rebound directly. Register custom CollisionDetector and Applier implementations through the facade methods above. Database creation and locking are internal defaults today rather than container-swappable contracts.

Running programmatically

php artisan isolate is a thin wrapper over the Isolate service, so you can run the same flow from your own code — an agent orchestrator, a custom command, a test — and inspect the result:

Events

Isolate dispatches the following events you can listen for:

• Ldiebold\Isolate\Events\IsolationApplied — after a plan is applied ($plan, $result).
• Ldiebold\Isolate\Events\DatabaseCreated — after a per-instance database is created ($result, $plan).
• Ldiebold\Isolate\Events\DatabaseDropped — after a per-instance database is dropped by isolate:teardown ($result, $plan). The $plan carries the instance's env map (e.g. REDIS_PREFIX), so listeners can clean up coupled resources.
• Ldiebold\Isolate\Events\PrefixFlushed — after a per-instance Redis keyspace is flushed by isolate:teardown ($result, $plan); fired once per prefix where keys were removed, with $result->keyCount.

The Isolate::after(...), Isolate::afterDatabaseCreated(...), Isolate::afterDatabaseDropped(...) and Isolate::afterPrefixFlushed(...) callbacks fire alongside these.

Conflict policy

By default conflicted candidate numbers are skipped (so --auto finds the next free one) and explicit --number / --reset selections warn about detected conflicts but proceed. Set throw_on_conflict (or ISOLATE_THROW_ON_CONFLICT=true) to fail fast on confirmed conflicts. Unavailable probes (DB down, Redis absent, no lock) always degrade with a warning, never a crash.

Testing

Postgres / MySQL database-creation tests are gated behind INTEGRATION_DB=1 (configure the server with the ISOLATE_PG_* / ISOLATE_MYSQL_* env vars). Everything else, including SQLite creation, runs without external services.

License

MIT.