Skip to content

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.

  • 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
  1. Create an API key

    In the dashboard, open Settings → Keys and create a key with the Full access preset, which includes the workers:run scope 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_key

    An 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_key to a .env file at the project root, and add .env to .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 status shows the same workspace. CHRONOS_API_KEY always 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.

  2. 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.
  3. 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 --json and chronos jobs create --wait --json. With the Node.js SDK, they come from chronos.account.get() and chronos.jobs.wait(). With the Go SDK, they come from client.Account.Get and client.Jobs.Wait.

  • 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.

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.

  1. 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:write scope. The “Full access” and “CI and deploys” presets both include it. This path needs no Node.js unless you pick the Node.js prompt.

  2. 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.
  3. Check the result

    The monitor shows as up in 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 from chronos monitors get <id> --json. With the Node.js SDK, it comes from chronos.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.