How to run an agent on a schedule

Pick the scheduler

Steps

1. Write the task down

   Put the prompt in a file. Say what to check, what counts as done and where the result goes: the agent cannot ask you halfway.

   $ mkdir -p ~/prompts ~/logs ~/bin
   $ cat > ~/prompts/nightly.md <<'EOF'
   Pull the latest main. Run npm test.
   If a test fails, fix the code, run the tests again and commit the fix.
   End with three lines: what failed, what you changed, what is left.
   EOF

2. Write the script

   Use full paths: cron starts with a short PATH and does not find ~/.local/bin. --allowedTools lists what the agent may do without asking; anything else is refused. Claude Code in -p mode exits with 0 on success and a non-zero code when the run fails.

   #!/bin/bash
   # ~/bin/nightly.sh
   set -euo pipefail
   cd /home/dev/your-project
   /home/dev/.local/bin/claude -p "$(cat /home/dev/prompts/nightly.md)" \
     --allowedTools "Read,Edit,Bash(git pull *),Bash(npm test *),Bash(git commit *)" \
     --output-format json > /home/dev/logs/nightly-$(date +%F).json

   With Codex, the same line is codex exec: -C sets the folder, -s the sandbox (read-only, workspace-write), -o writes the last message to a file.

   /home/dev/.local/bin/codex exec -C /home/dev/your-project -s workspace-write \
     -o /home/dev/logs/nightly-$(date +%F).txt "$(cat /home/dev/prompts/nightly.md)"

3. Run it once by hand

   Make it executable and run it. Fix every error now, while you can see it.

   $ chmod +x ~/bin/nightly.sh
   $ ~/bin/nightly.sh && echo "exit 0"
   $ jq -r '.result' ~/logs/nightly-$(date +%F).json

4. Schedule it with cron

   Open your crontab and add one line. Five fields: minute 0-59, hour 0-23, day of month 1-31, month 1-12, day of week 0-7 (0 and 7 are Sunday). This one runs every day at 07:00 server time.

   $ crontab -e
   # add:
   0 7 * * * /home/dev/bin/nightly.sh >> /home/dev/logs/cron.log 2>&1

5. Or schedule it with a systemd timer

   A timer catches up after a reboot: Persistent=true runs a missed job right after the machine comes back. A timer starts the service with the same name: agent.timer starts agent.service. Put both files in /etc/systemd/system/.

   # nightly-agent.service
   [Unit]
   Description=Nightly agent run
   
   [Service]
   Type=oneshot
   User=dev
   ExecStart=/home/dev/bin/nightly.sh
   
   # nightly-agent.timer
   [Unit]
   Description=Run the nightly agent at 07:00
   
   [Timer]
   OnCalendar=*-*-* 07:00:00
   Persistent=true
   
   [Install]
   WantedBy=timers.target

   $ sudo systemctl daemon-reload
   $ sudo systemctl enable --now nightly-agent.timer
   $ systemctl list-timers nightly-agent.timer

Check that it works

Set the schedule to every minute for a test, wait two minutes, read the log, then set it back. With a timer, start the service once by hand and read its journal.

$ tail -20 ~/logs/cron.log
$ sudo systemctl start nightly-agent.service
$ journalctl -u nightly-agent.service -n 30

The same job as an Uno scheduled task. The command runs as Uno's own user on the computer, which can use sudo; start your script as your user with sudo -u so the agent finds its sign-in, and a run gets 5 minutes by default and up to 60 minutes with timeout_sec:

$ curl -sS -X POST https://console.uno.place/api/v1/scheduled-tasks \
    -H "Authorization: Bearer $UNO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "nightly agent", "box_id": 1234,
         "cron_expr": "0 7 * * *", "timezone": "Europe/Berlin",
         "command": "sudo -u dev -H /home/dev/bin/nightly.sh",
         "timeout_sec": 3,600, "on_finish": "hibernate"}'

Every run is written to your access log as a scheduled task, so you can see when the agent ran and why.

What a schedule does not do

• It does not answer the agent's questions. A step that needs approval and is not in --allowedTools is refused, and the run ends without it.
• cron does not run what it missed while the server was off. A timer with Persistent=true does.
• It does not stop a run that goes wrong. Give each run a time limit: timeout 1h /home/dev/bin/nightly.sh in cron, TimeoutStartSec=1h in a Type=oneshot service.
• On Uno, a scheduled task does not wake a computer whose subscription is suspended or ended.

Common problems