Set up Chronos with your agent
Coding agents such as Claude Code, Cursor, and Codex can set Chronos up in a project on their own. chronos.sh/llms.txt gives them the facts and an index of these docs, and llms-full.txt holds every page as plain text. The one thing an agent cannot do on the pull path is create an API key.
Prerequisites
Section titled “Prerequisites”- A Chronos account with the owner or admin role (sign up free)
- A coding agent with shell access to the project
- Node.js 20 or later in the project for the pull worker, or Go 1.26 or later in a Go project
-
Create an API key
In the dashboard, open Settings → Keys and create a key with the Full access preset, which includes the
workers:runscope a pull worker needs. If no pull worker will use the key, the CI and deploys preset is enough. If you start the agent from this terminal, export the key here:Terminal window export CHRONOS_API_KEY=chrns_your_api_keyAn agent running in an app, an IDE, or another terminal does not see that export. In that case, add
CHRONOS_API_KEY=chrns_your_api_keyto a.envfile at the project root, and add.envto.gitignore.To check the key, call
GET /v1/account. It returns the workspace the key belongs to:Terminal window curl -s https://api.chronos.sh/v1/account -H "Authorization: Bearer $CHRONOS_API_KEY"If you have the CLI installed,
chronos auth statusshows the same workspace.CHRONOS_API_KEYalways overrides a saved browser login, so an agent with the key set never acts as you by accident.Keep the key out of the prompt and out of the repository. The agent reads it from the environment or from
.env. -
Paste this prompt
Use the CLI prompt. If the agent cannot install a binary, use the Node.js prompt.
Set up Chronos (https://chronos.sh) in this project so one job runs through it end to end.Read https://chronos.sh/llms.txt first and follow the links you need. Install the Chronos CLI with `curl -fsSL https://chronos.sh/install.sh | sh`. Use the CLI with --json to check the key and create jobs. If the script says its directory is not on PATH, add that directory to PATH for every later command. The CLI has no pull worker, so use the Node.js SDK (@chronos.sh/sdk, version 0.3.0 or later), or the Go SDK (chronos.sh/go, v0.3.0 or later) in a Go project, for it.The API key is in the CHRONOS_API_KEY environment variable, or in the project's git-ignored .env file. The CLI reads only the environment, so if the key is in .env, export it. Never print the key, hardcode it, or commit it. Check the key with `chronos auth status --json` and tell me the workspace name from account.name.Use pull delivery: add a worker with one handler and start it as a background process. Then run `chronos jobs create --name <name> --handler <handler> --wait --json`. Exit code 0 and a job status of completed confirm the job ran. If the command exits 9, run `chronos jobs wait <id> --json` and do not create another job. Finish by telling me the one command that starts the worker again from a clean shell.Set up Chronos (https://chronos.sh) in this project so one job runs through it end to end.Read https://chronos.sh/llms.txt first and follow the links you need. Use the Node.js SDK (@chronos.sh/sdk, version 0.3.0 or later), or the Go SDK (chronos.sh/go, v0.3.0 or later) in a Go project, for the pull worker and to create schedules and jobs.The API key is in the CHRONOS_API_KEY environment variable, or in the project's git-ignored .env file. Never print it, hardcode it, or commit it. Once the SDK is installed, check the key with chronos.account.get() (Go: client.Account.Get) and tell me the workspace name it returns.Use pull delivery: add a worker with one handler, start it as a background process, then create a one-off job for that handler. Confirm with chronos.jobs.wait(job.id) (Go: client.Jobs.Wait) that the job reached "completed". Finish by telling me the one command that starts the worker again from a clean shell. -
Check the result
The job and its execution appear in the dashboard under Jobs. The agent should also report the workspace name and the job status. With the CLI, they come from
chronos auth status --jsonandchronos jobs create --wait --json. With the Node.js SDK, they come fromchronos.account.get()andchronos.jobs.wait(). With the Go SDK, they come fromclient.Account.Getandclient.Jobs.Wait.
What to expect
Section titled “What to expect”- A one-off job runs as soon as the worker claims it, so the whole setup takes a few minutes.
- If the agent creates a recurring schedule instead, an interval schedule first runs one interval after creation (at least 10 minutes on the Free plan) and a cron schedule at its next matching time.
- Push delivery is a second option when the project already serves HTTP. Verifying push signatures needs your signing secret, which an API key cannot read, so you hand the agent that secret as well. See Push Delivery.
Monitor a job scheduled elsewhere
Section titled “Monitor a job scheduled elsewhere”A heartbeat monitor watches a job that Chronos doesn’t trigger, such as a crontab line or a CI workflow. The agent creates the monitor and adds a ping to the job. The ping is one HTTP request, so the job needs no SDK.
-
Give the agent an API key
Create a key and give the agent access to it as in the first step above. The key needs the
monitors:writescope. The “Full access” and “CI and deploys” presets both include it. This path needs no Node.js unless you pick the Node.js prompt. -
Paste this prompt
Replace the placeholder in the first line with the job: what it does, where it runs, how often, and how long a run takes. If the agent may run the job, say so there too.
Add a Chronos (https://chronos.sh) heartbeat monitor to this job: <the job, where it runs, how often, and how long a run takes>. Chronos does not trigger the job. The job reports to Chronos.Read https://chronos.sh/llms.txt first, then https://chronos.sh/docs/monitors and the guide there for the job's platform. Install the Chronos CLI with `curl -fsSL https://chronos.sh/install.sh | sh`. If the script says its directory is not on PATH, add that directory to PATH for every later command.The API key is in the CHRONOS_API_KEY environment variable, or in the project's git-ignored .env file. The CLI reads only the environment, so if the key is in .env, export it. Never print the key, hardcode it, or commit it.Create the monitor with `chronos monitors create --name <name> --cron '<expression>' --timezone <timezone> --grace <duration> --json`, or with --interval <duration> in place of --cron and --timezone. Use the job's own schedule, and a grace period longer than a run takes. If the command exits 7, run `chronos monitors list --search <name> --json` before you create the monitor again.The ping_url in the output is a secret. Never print it. Read it from the JSON straight into the secret store the job already reads its other secrets from. Never put it in a committed file, even where the platform guide shows it inline. If you cannot write to that secret store, tell me the name of the secret to set, and I will copy the URL from the dashboard.When the job finishes, make it send one plain HTTP request to the ping URL that reports success or failure, as the platform guide shows. Unless I said the job is safe to run, do not run it. Send one success ping to the stored URL from the shell instead. Then confirm with `chronos monitors get <id> --json` that the status is up, without printing the ping URL. Finish by telling me the monitor id and where the ping URL is stored.Add a Chronos (https://chronos.sh) heartbeat monitor to this job: <the job, where it runs, how often, and how long a run takes>. Chronos does not trigger the job. The job reports to Chronos.Read https://chronos.sh/llms.txt first, then https://chronos.sh/docs/monitors and the guide there for the job's platform. Use the Node.js SDK (@chronos.sh/sdk, version 0.5.0 or later) from a one-off script to create and check the monitor. Add the SDK to the project's dependencies only if the project already uses Node.js. The SDK sends no pings.The API key is in the CHRONOS_API_KEY environment variable, or in the project's git-ignored .env file. Never print it, hardcode it, or commit it.Create the monitor with chronos.monitors.create(). Pass the job's own cron expression and timezone, or its interval. Set grace_seconds longer than a run takes. If chronos.monitors.create() throws a network error or a 5xx, look for the monitor with chronos.monitors.list({ search: name }) before you create it again.The ping_url that chronos.monitors.create() returns is a secret. Never log it. Write it straight into the secret store the job already reads its other secrets from. Never put it in a committed file, even where the platform guide shows it inline. If you cannot write to that secret store, tell me the name of the secret to set, and I will copy the URL from the dashboard.When the job finishes, make it send one plain HTTP request to the ping URL that reports success or failure, as the platform guide shows. Unless I said the job is safe to run, do not run it. Send one success ping to the stored URL from the shell instead. Then confirm with chronos.monitors.get(id) that the status is "up", without logging the ping URL. Finish by telling me the monitor id and where the ping URL is stored. -
Check the result
The monitor shows as
upin the dashboard under Monitors, and its ping history shows the test ping. The agent should also report the monitor id. With the CLI, the status comes fromchronos monitors get <id> --json. With the Node.js SDK, it comes fromchronos.monitors.get(id).
From now on, the monitor alerts when a fail ping arrives, or when no success or fail ping arrives within the grace period after the job was due. See Cadence and grace period.