> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/hybrid-hivel-agent/3.-prerequisites-and-set-up/step-9-scheduling.md).
# Step 9 - Scheduling
hivel-agent has no built-in scheduler - use your own cron / systemd timer. sync and work-metrics are independent commands with different recommended cadences; run them as separate cron entries.
Add this to the crontab on the same machine where you installed the agent.
#### **sync - once daily**
```
# crontab - daily at midnight UTC
0 0 * * * cd /opt/hivel-agent && ./hivel-agent --config config.yml --env-file .env sync
--no-progress >> /var/log/hivel-agent.log 2>&1
```
The agent does not need to run more often - each run only pulls incremental changes since the last sync.
#### **work-metrics - hourly (Bitbucket / Azure DevOps / GitHub / GitLab only)**
Only needed if you're using the work-metrics classification job. Its default --time-budget is 50 minutes specifically so one run finishes before the next hourly run starts - schedule it accordingly:
```
# crontab - every hour, at 15 minutes past
15 * * * * cd /opt/hivel-agent && ./hivel-agent --config config.yml --env-file .env work-metrics
>> /var/log/hivel-agent-work-metrics.log 2>&1
```
If you lower --time-budget below 50 minutes, you can schedule more frequently than hourly; if you raise it, widen the interval to match so runs don't overlap.
#### **Checking agent status & logs**
hivel-agent is not a long-running daemon - each sync or work-metrics invocation runs once and exits. "Is it running" splits into a few different real questions:
**Is a run in progress right now?**
```
pgrep -f hivel-agent
```
No output means nothing is currently executing.
Did the last scheduled run succeed? For sync/work-metrics run via cron with no --output-dir (the normal case, as in the examples above), the agent writes its full structured log to both stdout and a fresh temp directory on every run - that temp path isn't printed anywhere, so it's not practically discoverable after the fact. The reliable way to check what happened is the log file your own cron redirect writes to:
```
tail -100 /var/log/hivel-agent.log
tail -100 /var/log/hivel-agent-work-metrics.log
```
This is exactly why the cron examples above redirect stdout/stderr to a fixed file - set that up before you rely on cron for anything unattended.
Structured \`status.json\` / \`summary.json\` / \`diagnostics.json\` (see Files generated per run) only land somewhere durable and inspectable if you pass --output-dir - sync is the one command here that doesn't accept that flag (work-metrics does, via --output-dir, download-only mode). If you're running plain sync on a schedule and need persistent structured status rather than a log stream, use the download → review → send workflow instead.
#### **Is the schedule itself actually firing?**
```
crontab -l # confirm the cron entry exists
grep CRON /var/log/syslog # Linux: confirm cron actually triggered it
systemctl list-timers # systemd timer: confirm it's scheduled
journalctl -u hivel-agent.service --since today # systemd: run history
```
{% columns %}
{% column %} Step 8
{% endcolumn %}
{% column %}
{% endcolumn %}
{% column %} Commands & Workflow
{% endcolumn %}
{% endcolumns %}