Guide: dispatch a run from cron or a script
This guide is for someone who already has a working run from a terminal
(guide-unattended-run.md) and wants the same run
to start on a timer or from another program. At the end you will have a script
that cron can call, you will know what its exit code means, and you will know
when to use skep's own schedules instead.
The thing that goes wrong first
Cron does not run your shell's startup files. A job gets a short PATH
(often /usr/bin:/bin) and almost no other variables. Three things your
terminal had are missing:
skepitself, if pipx installed it under~/.local/bin.- The agent's CLI (
claude,codex), usually also under your home. - The agent's credential (
CLAUDE_CODE_OAUTH_TOKEN,ANTHROPIC_API_KEYorOPENAI_API_KEY), which you exported in your shell.
skep refuses each case before anything starts, with exit code 2. Both of these were produced under a cron-like environment.
With the agent's CLI not on PATH:
error: coding_engine 'claude_code' is not installed here ('claude' not on PATH) — `skep doctor` lists each engine; install it, or switch the project to another engine (`skep project setup --engine builtin`)
next: skep doctor # engines, auth env, sandbox
With PATH fixed and no credential:
error: coding_engine 'claude_code': NO AUTH ENV — set one of CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY in the environment the worker inherits (the daemon reads <home>/serve.env at startup; `skep run` uses your shell) — the line `skep doctor` prints for this engine
next: skep doctor # engines, auth env, sandbox
And when skep itself is not on PATH, the shell answers before skep can
(exit code 127):
/bin/sh: line 1: skep: command not found
Log the job's output (step 4) so you can see which one you have.
What you need first
- The run works from your terminal, with the project already set up: engine, pinned verify command.
- The absolute paths of
skepand of the agent's CLI:command -v skep,command -v claude. - If you use a non-default home, its path.
--homegoes before the subcommand:skep --home /path/to/home run …, or setSKEP_HOME.
1. Put the credential in a file only you can read
mkdir -p ~/.config/skep
umask 077
printf 'CLAUDE_CODE_OAUTH_TOKEN=%s\n' 'paste-the-token-here' > ~/.config/skep/cron.env
chmod 600 ~/.config/skep/cron.env
Do not put the token in the crontab line: crontabs are often readable by backups and shown in process listings.
2. Write the wrapper
#!/bin/sh
# ~/bin/skep-nightly.sh
set -eu
# cron has none of your shell's environment: say where things are.
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
# the agent's credential, exported for the worker to inherit
set -a
. "$HOME/.config/skep/cron.env"
set +a
exec skep run "$HOME/code/calc" "make the failing test pass" \
--execution-mode sandbox --quiet
chmod 700 ~/bin/skep-nightly.sh
--quiet drops the live progress lines and keeps the summary:
task 01a1f134-77b5-7815-954f-11c0d8686bb1
state: completed (1.6s)
verification: confirmed by re-verify (G10) — re-ran <verify command> → exit 0
worker claim: passed — created hello.py and verified it runs.
evidence: /home/you/.skep/supervisor/audit/01a1f134-77b5-7815-954f-11c0d8686bb1
next: skep review 01a1f134-77b5-7815-954f-11c0d8686bb1
3. Test it the way cron will run it
Before trusting the timer, run the wrapper with an empty environment:
env -i HOME="$HOME" ~/bin/skep-nightly.sh; echo "exit $?"
If this works, cron will work. If it prints one of the errors above, fix
PATH or the env file. Run this way with an env file that held no credential,
the wrapper printed the NO AUTH ENV refusal and exited 2; pointed at a
project on the built-in worker it printed the summary block and exited 0.
4. Add the cron line
15 2 * * * $HOME/bin/skep-nightly.sh >> $HOME/.cache/skep-nightly.log 2>&1
A run is not interactive under cron. If the worker stops to ask for a
permission, the run ends in state pending_approval with exit code 4 and
waits for skep review <task_id> --approve, --deny or --allow-command.
Nothing is approved on your behalf.
5. Use the exit code
| Exit | State | What a script should do |
|---|---|---|
| 0 | completed |
the worker finished; check re-verification before trusting it |
| 2 | refused or a usage error | nothing ran; read the message (PATH, credential, verify command, sandbox) |
| 3 | failed |
the worker gave up; the summary line says why |
| 4 | pending_approval |
a human answer is needed: skep review <task_id> |
| 5 | rejected |
policy or a human denied it |
| 6 | worker_timeout |
the budget ran out; raise --budget-wall-clock or narrow the task |
| 7 | worker_crashed |
the worker died; see worker.log in the evidence directory |
Exit 0 is not "the patch is good". In a run made for this guide the worker
reported passed, skep's re-run of the project's command failed, and the exit
code was still 0. The patch is held either way; to see which runs skep did not
confirm:
skep status --personal
⚠ 2 completed run(s) NOT confirmed by re-verification (G10):
skep review 01a1f131-762b-77f5-86a7-9cc9de4a8342 # worker claimed passed; supervisor re-run disagreed
skep review 01a1f131-5eeb-7c0d-85ec-8a2239d4e924 # worker claimed passed; supervisor re-run disagreed
A scheduled run does not land anything unless the project has auto-landing
switched on (guide-auto-landing.md). Otherwise each
run waits for your skep review <task_id> --approve.
skep's own schedules: skep schedule and skep tick
skep can also keep the timetable itself. You add a schedule once, and a single
cron line calls skep tick, which dispatches whatever is due.
skep schedule add notes-hello ~/code/notes "Write a Python hello world script" --every 30s
scheduled 'notes-hello': coding on /home/you/code/notes every 30s
next run: 2026-11-19T00:26:39Z (dispatch due work with: skep tick)
--every takes 30s, 5m, 2h or 1d. Thirty seconds was used here so the
schedule came due during the session; for a nightly run use 1d.
skep schedule list
name caste every on next run last run last outcome source
calc-nightly coding 30s yes 2026-11-19T00:27:39Z 2026-11-19T00:27:13Z failed inline
notes-hello coding 30s yes 2026-11-19T00:27:39Z 2026-11-19T00:27:13Z completed inline
skep tick
ran 'calc-nightly': 01a1f133-4dfc-7e38-9217-300c52e19efc (failed)
ran 'notes-hello': 01a1f133-5400-7f6f-b79c-120afe883acc (completed)
When nothing is due it prints no schedules due. skep schedule health shows
each schedule's failures and success rate, and skep schedule remove NAME
deletes one.
*/15 * * * * $HOME/.local/bin/skep tick >> $HOME/.cache/skep-tick.log 2>&1
Three things to know before choosing this over the wrapper:
- A scheduled run uses skep's built-in worker, not the project's pinned
engine. On 1.4.2,
calcabove pinsclaude_code, and the scheduled run was still handed to the built-in worker (--worker-cmdonskep tickchanges which worker command that is). The project's verify command and landing policy do apply. To run Claude Code or Codex on a timer, use the wrapper withskep run, which honours the pin. skep tickexits 0 whatever the runs did. The states are in its output and inskep schedule health, not in the exit code.- Project setup creates a schedule.
skep project setupon atrusted_local_devrepository adds<project>-maintain-weeklyunless you pass--no-seed-schedules. The firstskep tickafter it comes due will run it.skep schedule listshows what is there.
skep tick --auto-approve is retired: it is still accepted, prints a note,
and lands nothing.
What a running skep serve does by itself
If skep serve is running, you do not need a cron line for schedules: the
daemon dispatches due schedules itself, through the same code as skep tick
(and with the same built-in-worker limit).
The daemon has cron's problem too if a service manager starts it: it does not
have your shell's variables. For that it reads <home>/serve.env at startup,
one KEY=VALUE per line. A variable already set in its environment wins over
the file, and the startup banner prints the names it loaded, never the values:
serve.env: loaded CLAUDE_CODE_OAUTH_TOKEN
Keep that file at mode 600. It is read once, at startup: after changing it,
restart skep serve.
What goes wrong, and how to tell
| What you see | Cause | Fix |
|---|---|---|
| nothing in the log, nothing ran | skep is not on cron's PATH |
use the absolute path, or set PATH in the wrapper |
is not installed here ('claude' not on PATH) |
the agent's CLI is not on cron's PATH |
add its directory to PATH in the wrapper |
NO AUTH ENV |
the credential is not exported in the job | steps 1 and 2; check with step 3 |
| exit 4 every night | the worker asks for a permission nobody is there to answer | approve it once with skep review <task_id> --allow-command, or widen the project policy |
a schedule on a Claude Code project "fails" with minimal coding worker only supports Python hello-world tasks |
scheduled runs use the built-in worker, and no model is configured for it | use the wrapper with skep run |
| runs you did not schedule | the seeded <project>-maintain-weekly schedule |
skep schedule remove <name> |
| two runs of the same schedule | both skep serve and a cron skep tick are dispatching on one home |
keep one of them |