Agent Guide
The Crontinel agent is a lightweight daemon that runs on your server, connects to app.crontinel.com, and polls for remote commands. It enables cloud-triggered cron execution — schedule a command from the dashboard and the agent runs it on your server.
How It Works
- The agent connects to Crontinel Cloud using your API key
- It polls for new commands every 5 seconds (see Connection Method)
- When a trigger is scheduled from the dashboard, the agent checks the command against your configured allowlist
- If allowed, it executes the command and reports the result (success or failure, exit code, output) back to the cloud; if not allowed, it reports a rejection and does not run it
- A heartbeat is sent every 60 seconds to confirm the agent is alive
Connection Method
Every agent registers at /api/v1/agents/register, polls app.crontinel.com/api/v1/agents/{id}/commands every 5 seconds, and sends heartbeats to /api/v1/agents/heartbeat every 60 seconds.
Laravel Agent
The Laravel package (crontinel/laravel) includes a built-in agent command.
Prerequisites
crontinel/laravelv0.9.11 or later. Earlier versions could not connect to the hosted app.CRONTINEL_API_KEYset in.env- The commands it may run listed in
crontinel.agent.allowed_commands(see the configuration reference). The default empty list rejects every command and reports it as failed.
Start the Agent
php artisan crontinel:agentProduction Setup
Generate a systemd unit file:
php artisan crontinel:agent --systemdOr a supervisor config:
php artisan crontinel:agent --supervisorOther runtimes
The agent ships only in the Laravel package. The Node and Python packages have no installable agent: @crontinel/node on npm has no crontinel agent command, and the Python package (on PyPI) has no agent command.
Check-in alerts
Set how often an agent should check in from Configure on its row in the dashboard: an expected interval and a grace period.
- Missed: when an agent misses its expected check-in, Crontinel sends an alert. When it checks in on time again, you get a recovery notice. A repeat of the same alert waits at least 15 minutes.
- Late: turn on Alert when late to also get a separate alert once a check-in is past its interval. It is off by default and recovers when the agent is on time.
To silence one agent for a while, use the mute control on its row. See muting alerts.
Command Allowlisting
The agent will only execute commands that match an entry in your allowlist. An unconfigured or empty allowlist means no commands are permitted — this is the default, fail-closed behavior.
Patterns support exact string matches and * as a wildcard (e.g. php artisan queue:* allows any queue: subcommand).
Laravel — publish the config (php artisan vendor:publish --tag=crontinel-config) and set allowed_commands in the agent block of config/crontinel.php:
'agent' => [ // ... 'allowed_commands' => [ 'php artisan queue:restart', 'php artisan horizon:terminate', 'php artisan queue:*', ],],A rejected command is reported back to the dashboard as failed with the reason “Command rejected: not in allowlist,” so you can see rejections in your trigger history and adjust the allowlist as needed.
Systemd Service
Create /etc/systemd/system/crontinel-agent.service:
[Unit]Description=Crontinel Agent DaemonAfter=network.target
[Service]Type=simpleUser=www-dataWorkingDirectory=/path/to/your/appEnvironment=CRONTINEL_API_KEY=your-api-keyExecStart=/usr/bin/php artisan crontinel:agentRestart=alwaysRestartSec=10
[Install]WantedBy=multi-user.targetEnable and start:
sudo systemctl enable crontinel-agentsudo systemctl start crontinel-agentSupervisor Config
Create /etc/supervisor/conf.d/crontinel-agent.conf:
[program:crontinel-agent]command=php artisan crontinel:agentdirectory=/path/to/your/appuser=www-dataautostart=trueautorestart=truestartretries=3stderr_logfile=/var/log/crontinel-agent.err.logstdout_logfile=/var/log/crontinel-agent.out.logReload and start:
sudo supervisorctl rereadsudo supervisorctl updatesudo supervisorctl start crontinel-agentEnvironment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
CRONTINEL_API_KEY | Yes | — | Your API key from app.crontinel.com/settings |
CRONTINEL_API_URL | No | https://app.crontinel.com | API base URL (change only for self-hosted) |
Testing
-
Add the command you want to test to your allowlist — untested commands are rejected by default
-
Create a trigger with the app’s API key:
Terminal window curl -X POST https://app.crontinel.com/api/v1/triggers \-H "Authorization: Bearer $CRONTINEL_INGEST_KEY" \-H "Content-Type: application/json" \-d '{"command": "php artisan inspire"}' -
Watch the agent run it. The trigger and its result show on the app’s Triggers tab
Troubleshooting
Agent won’t start
- Verify
CRONTINEL_API_KEYis set - Check network connectivity to
app.crontinel.com
Agent starts but no commands received
- Verify the app ID matches your app in the dashboard
- Check that triggers are being dispatched (the app’s Triggers tab)
Agent crashes repeatedly
- Check the agent’s output in your systemd journal or supervisor log files
- Ensure the agent user has permission to execute the scheduled commands
Commands are rejected / never execute
- Check the trigger’s result on the dashboard for “Command rejected: not in allowlist”
- Verify the command matches an entry in your allowlist exactly, or via a
*pattern - Remember the default allowlist is empty — nothing runs until you configure one