README

minitor/agent

Self-hosted replacement for Laravel Nightwatch's closed-source local agent (agent.phar). Installing this package pulls in the official, unmodified laravel/nightwatch package as a dependency - that's the real Laravel-maintained instrumentation (request timing, query listener, exception handler, queue events, etc.), completely untouched. This package only replaces the piece Laravel never open-sourced: the local agent that receives from it. Instead of forwarding to Laravel's hosted service, it forwards to your own self-hosted MINITOR server.

laravel/nightwatch already knows how to talk to a local agent on 127.0.0.1:2407 - this package speaks that same protocol, so no changes to laravel/nightwatch or your application code are needed.

This package is only useful alongside a running MINITOR server. See github.com/enioladev1/minitor to self-host that first - it's where you create a project and get both values this agent needs below. You never invent or generate either one yourself; the dashboard generates both together and shows them as a ready-to-paste snippet in the project's Settings dialog.

Install

On the Laravel app you want to monitor, one command installs both this agent and laravel/nightwatch itself:

composer require minitor/agent

Paste the snippet from your project's Settings dialog into .env - it looks like this, with both values already filled in for you:

NIGHTWATCH_TOKEN=<generated by the MINITOR dashboard for this project>
MINITOR_SERVER_URL=https://minitor.example.com
MINITOR_PROJECT_TOKEN=<generated by the MINITOR dashboard for this project>

Nightwatch's own NIGHTWATCH_INGEST_URI (what this agent listens on) and this agent's MINITOR_AGENT_LISTEN already default to the same 127.0.0.1:2407, so nothing extra is needed there unless you're changing that port.

NIGHTWATCH_TOKEN never leaves this server - it's only used locally to verify frames came from this app's own Nightwatch instance. It's named NIGHTWATCH_TOKEN (not something MINITOR-branded) because that's the exact environment variable the real, unmodified laravel/nightwatch package reads for it - we can't rename that without forking Nightwatch. MINITOR_PROJECT_TOKEN is what authenticates this app's data to your central MINITOR dashboard. Regenerating the project in the dashboard rotates both values together - update .env again after doing so.

Run the agent (keep it running with Supervisor, systemd, Forge's daemon manager, etc. - same operational requirement as Nightwatch's own agent):

php artisan minitor:agent

Configuration

Publish the config file to customize buffer thresholds or which record types get forwarded:

php artisan vendor:publish --tag=minitor-config

See config/minitor.php for all options.

How it works

laravel/nightwatch frames every batch of telemetry as {length}:{version}:{tokenHash}:{payload} and sends it over a local TCP connection, expecting a 4-byte 2:OK acknowledgement back - this is exactly what Laravel's real (closed-source) agent does too. This package's AgentServer implements that same protocol (see src/Protocol/FrameDecoder.php and src/Protocol/TokenHasher.php), decodes each record, buffers them, and forwards batches to your MINITOR server's POST /api/ingest over HTTPS.

Testing

composer install
./vendor/bin/phpunit

License

MIT