Skip to content

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

  1. The agent connects to Crontinel Cloud using your API key
  2. It polls for new commands every 5 seconds (see Connection Method)
  3. When a trigger is scheduled from the dashboard, the agent checks the command against your configured allowlist
  4. 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
  5. 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/laravel v0.9.11 or later. Earlier versions could not connect to the hosted app.
  • CRONTINEL_API_KEY set 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

Terminal window
php artisan crontinel:agent

Production Setup

Generate a systemd unit file:

Terminal window
php artisan crontinel:agent --systemd

Or a supervisor config:

Terminal window
php artisan crontinel:agent --supervisor

Other 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 Daemon
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/your/app
Environment=CRONTINEL_API_KEY=your-api-key
ExecStart=/usr/bin/php artisan crontinel:agent
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

Enable and start:

Terminal window
sudo systemctl enable crontinel-agent
sudo systemctl start crontinel-agent

Supervisor Config

Create /etc/supervisor/conf.d/crontinel-agent.conf:

[program:crontinel-agent]
command=php artisan crontinel:agent
directory=/path/to/your/app
user=www-data
autostart=true
autorestart=true
startretries=3
stderr_logfile=/var/log/crontinel-agent.err.log
stdout_logfile=/var/log/crontinel-agent.out.log

Reload and start:

Terminal window
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start crontinel-agent

Environment Variables

VariableRequiredDefaultDescription
CRONTINEL_API_KEYYes—Your API key from app.crontinel.com/settings
CRONTINEL_API_URLNohttps://app.crontinel.comAPI base URL (change only for self-hosted)

Testing

  1. Add the command you want to test to your allowlist — untested commands are rejected by default

  2. 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"}'
  3. 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_KEY is 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