Processes, workers and cron
Falak’s agent includes a process supervisor and a cron scheduler. You declare what should run in the site’s Processes tab; Falak compiles the full desired set per server and the agent converges to it. No supervisord, no crontab editing.
Kinds of processes
Section titled “Kinds of processes”| Kind | Program name | Created by |
|---|---|---|
| Web process (Node, Bun, Deno) | <slug>.app |
Automatically for JavaScript runtimes |
| Queue worker | <slug>.worker-<id> |
You (Processes → Queue workers) |
| Horizon | <slug>.horizon |
Settings → Laravel → Horizon |
| Octane | <slug>.octane |
Settings → Laravel → Octane |
| Daemon | <slug>.daemon-<id> |
You (Processes → Daemons) |
| Laravel scheduler | <slug>.schedule |
Settings → Laravel → Scheduler (leader only) |
| Cron job | <slug>.cron-<id> |
You (Processes → Scheduled jobs) |
All run in current/ of the site, as the site user, with the release’s environment plus FALAK_SITE, FALAK_SITE_ID, FALAK_SERVER_ID, FALAK_RELEASE_ID and FALAK_DEPLOYMENT_ID.
Queue workers
Section titled “Queue workers”- Open the site’s Processes tab → Queue workers → Add.
- Fill in the fields below and save. The workers start on every selected server that has a live release.
| Field | Meaning | Allowed |
|---|---|---|
| Connection | Queue connection name (empty = the app default) | letters, digits, _ . - |
| Queue | Queue names, comma-separated (empty = default) |
|
| Processes | Parallel worker processes | 1–64 |
| Timeout | --timeout seconds |
0–86400 |
| Sleep | --sleep seconds |
0–3600 |
| Tries | --tries |
0–1000 |
| Backoff | --backoff seconds |
0–86400 |
| Max jobs | --max-jobs |
0–1000000 |
| Max time | --max-time seconds |
0–604800 |
| Memory | --memory MB |
32–65536 |
| Command | Replaces artisan queue:work entirely (run with bash -c) |
|
| Environment | Extra variables (up to 50) | |
| Servers | Subset of the site’s servers (default: all) |
Generated command for PHP sites:
php8.4 artisan queue:work redis --queue=high,default --sleep=3 --tries=3 --timeout=60 --memory=128 --backoff=10Non-PHP sites must set Command (for example node dist/worker.js).
Daemons
Section titled “Daemons”Any long-running command: a WebSocket server, bin/console messenger:consume, a BullMQ consumer.
| Field | Meaning | Allowed |
|---|---|---|
| Name | Label | up to 64 characters |
| Command | Command line | up to 2000 characters |
| Directory | Absolute working directory (default: current/) |
|
| User | Linux user (not root) |
default: site user |
| Instances | Processes to run | 1–64 |
| Restart | always, on-failure, never |
|
| Stop signal | TERM, INT, QUIT, HUP, KILL, USR1, USR2 |
|
| Stop timeout | Seconds before SIGKILL |
1–3600 |
| Environment, Servers | As for workers |
Scheduled jobs (cron)
Section titled “Scheduled jobs (cron)”| Field | Meaning |
|---|---|
| Name, Command | What to run |
| Expression | 5-field cron (*/5 * * * *), @hourly, @daily, @weekly, @monthly, @yearly, or @every <duration> (Go duration, at least 1 s, e.g. @every 90s) |
| Timezone | IANA timezone (default UTC) |
| User | Not root |
| Overlap | allow or skip (skip a run while the previous one is still running) |
| Timeout | 1–86400 seconds |
| Heartbeat | Report each run to Insights so missed runs are detected |
| Enabled | Pause without deleting |
| All servers | Run on every server, or only on the leader |
The Laravel scheduler is a built-in job: php artisan schedule:run every minute on the leader, overlap allowed, heartbeat on, timeout 3600 s.
Lifecycle
Section titled “Lifecycle”- Nothing runs before the first deployment. A site’s programs and cron jobs start on a server once the site has a live release there. A server added to a deployed site gets them at the next deployment.
- Deploys restart processes. After activation, the restart phase applies the new process set; every program whose definition (including environment) changed restarts in the new release. Horizon receives
horizon:terminate; Octane is restarted. - Restart processes in the panel menu restarts the site’s processes on the same release (Octane gets a graceful
octane:reload). - Process changes are debounced by 2 seconds (
FALAK_PROCESSES_APPLY_DELAY), then applied as oneproc.apply/cron.applyper server. - Restarting the agent restarts supervised programs.
Crash loops
Section titled “Crash loops”Every 5 minutes (FALAK_PROCESSES_STATUS_POLL, 0 disables) Falak polls the status of programs. A program that is fatal, or in backoff after 5 or more restarts, raises the Process keeps crashing alert (processes.crash_loop, critical). Process running again (processes.recovered) follows when it recovers.
Program output goes to /var/log/falak on the server and is shipped to Loki. See it in the site’s Logs tab.
Limits
Section titled “Limits”- Processes are not run for Docker and Compose sites (container runtimes). Add them as containers.
- Cron jobs and daemons cannot run as
root.