README

The official monitoring agent for LaraFleet – the monitoring platform for Laravel applications.

Installation

composer require larafleet/agent
php artisan larafleet:install

The install command prompts for your API key from the LaraFleet dashboard and updates .env automatically.

How it works

The agent runs larafleet:heartbeat every 5 minutes via the Laravel Scheduler. Only the standard cron entry is required — no queue worker or Supervisor needed:

* * * * * php /path-to-app/artisan schedule:run >> /dev/null 2>&1

Cheap collectors (Queue, Scheduler, Disk) run on every heartbeat. Expensive collectors (Composer, npm, Laravel/PHP version, Env) run once per hour.

This reduces snapshot rows in the dashboard from ~288 to ~24 per project per day.

What data is sent?

Exception Reporting

Unhandled exceptions are automatically forwarded to LaraFleet — no extra setup required after installation. The agent hooks into Laravel's exception handler and sends a signed report to POST /api/exceptions.

What is reported:

Filtering: the following request keys are replaced with [FILTERED] before transmission: password, password_confirmation, current_password, token, api_key. Custom keys can be added via exceptions.dontFlash.

Disabling:

LARAFLEET_EXCEPTIONS_ENABLED=false

Or extend exceptions.dontReport in config/larafleet-agent.php to suppress specific exception classes:

'exceptions' => [
    'dontReport' => [
        \App\Exceptions\MyExpectedException::class,
    ],
],

Security

• Every request is signed with HMAC-SHA256
• Replay protection: requests older than 60 seconds are rejected by the server
• Env whitelist: only explicitly allowed keys are transmitted
• Input filtering: sensitive request parameters are never transmitted in plain text
• No SSH credentials, no passwords, no full .env files

Configuration

php artisan vendor:publish --tag=larafleet-agent-config

All options in config/larafleet-agent.php:

Dispatch mode

By default the heartbeat runs synchronously inside the Scheduler process (dispatch=command). For apps that already have a running Queue Worker, set LARAFLEET_DISPATCH=job in .env to offload the heartbeat to the queue instead.

License

MIT