Scheduled Processes

Scheduled Processes

Procodile supports scheduled processes alongside normal long-running processes.

Scheduled processes are for jobs that run on a schedule instead of staying up continuously.

Defining a Scheduled Process

You can define a scheduled process in either of two ways.

In Procfile

Use __AT__ between the process name and a cron expression:

"cleanup__AT__*/10 * * * * *": bundle exec rake cleanup

Rules:

• __AT__ must use an uppercase AT, with exactly two underscores on each side.
• The cron expression uses the traditional five-field crontab format, with optional support for a leading sixth field for seconds.
  • second (optional)
  • minute
  • hour
  • day
  • month
  • weekday

In the Options Files

processes:
  cleanup:
    at: "*/10 * * * * *"

This is equivalent to the Procfile example above.

If both the Procfile and the options files define a schedule for the same process, the options files take precedence.

It's often a good idea to use a cron_ prefix in the process name for this case, for example cron_cleanup. This makes it easier to recognize the entry as a scheduled job rather than a normal long-running service.

Runtime Behavior

Scheduled processes behave differently from normal daemon-style processes.

They do not stay running

Each run creates a process, waits for it to finish, records the result, and then removes that instance.

They do not run immediately on start

procodile start enables the schedule. It does not execute the job immediately.

They do not run immediately on restart

procodile restart -p job reloads and re-enables the schedule. It does not execute the job immediately.

reload applies schedule changes immediately

If you change a schedule and run:

procodile reload

the new schedule becomes active immediately.

Adding Random Delay

Procodile also supports random_delay for scheduled processes in the options files. The value is in seconds and only delays execution forward.

For example:

processes:
  cleanup:
    at: "*/10 * * * * *"
    random_delay: 600

This is roughly equivalent to wrapping the command with something like sleep $((RANDOM % 600)) before running the real work.

If you want to do it manually, the simplest approach is to wrap the command yourself.

For example:

"cleanup__AT__*/10 * * * * *": bash -lc 'sleep $((RANDOM % 600)); exec bundle exec rake cleanup'

This keeps the schedule itself unchanged, but delays the actual work by a random number of seconds.

This approach depends on bash because $RANDOM is a Bash feature.

Overlap Behavior

Procodile does not allow overlapping runs of the same scheduled process.

If a previous run is still active when the next scheduled time arrives:

• the new run is skipped
• the current run continues

If this happens repeatedly, Procodile raises a runtime issue so it is visible in CLI output and status.

Stopping a Scheduled Process

For scheduled processes:

• job refers to the scheduled task itself.
• job.3 refers to a specific currently running instance, You can get the instance name from procodile status.

Stopping the scheduled task itself only disables future runs.

procodile stop -p job

Stopping a scheduled instance also disables future scheduling for that job.

procodile stop -p job.3

Restarting a Scheduled Process

procodile restart -p cleanup

This reloads the schedule and re-enables it. It does not force an immediate run.

If you want to restart only a currently running scheduled instance, target that instance explicitly:

procodile restart -p cleanup.3

This restarts that running instance and, if future scheduling was previously disabled, re-enables it.

Status Output

Scheduled processes display schedule-specific status:

• Schedule
• Last Started At
• Last Finished At
• Last Exit Status
• Last Run Duration
• Random Delay when configured, shown as the maximum delay

They do not display daemon-only fields such as quantity or restart mode.

Invalid Schedule Errors

If the cron expression is invalid, Procodile records a runtime issue and explains the expected format.

Example:

Scheduled process 'cleanup' has invalid cron schedule '...'

After fixing the schedule, run either:

procodile reload

or:

procodile restart -p cleanup

to restore it.