Scheduling Simulations

Run simulations on a schedule—daily, on push, or at a fixed time—so you get ongoing validation without manual runs. Okareo provides a CLI and SDK you can use to run simulations on a schedule from your own CI/CD or cron-based automation.

Options for Scheduled Runs

Approach	How it works	Best for
CI on schedule	Use a scheduled workflow (e.g. GitHub Actions schedule:, CircleCI cron) to run the Okareo CLI or SDK.	Daily or weekly regression; recurring validation.
CI on push	Run simulations on every push or PR so each change is validated immediately.	Pre-deploy checks; no separate schedule.
Cron + CLI	A cron job on a server runs okareo run (or an SDK script) at a fixed time.	Simple recurring runs without a full CI setup.

All of these use the same Running Simulations model: one Target, one Driver, one Scenario (with N rows × repeats). The only difference is who triggers the run—a scheduler instead of a human.

1. Scheduled CI workflow (e.g. GitHub Actions)

Use your CI platform’s scheduled trigger to run your Okareo flow (CLI or SDK) on a cron expression.

Example: GitHub Actions — run simulations every night

name: Nightly Simulations
on:
    schedule:
        - cron: "0 2 * * *" # 2 AM UTC daily
    workflow_dispatch: # allow manual run
env:
    OKAREO_API_KEY: ${{ secrets.OKAREO_API_KEY }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
jobs:
    simulate:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: okareo-ai/okareo-action@v2.5
            - name: Run simulation flow
              run: okareo run -f my_simulation_flow

Your flow (e.g. my_simulation_flow in .okareo/flows/) would use the CLI or SDK to run a simulation (Target + Driver + Scenario) and optionally fail the job if checks don’t pass. See GitHub Actions for full setup (secrets, working directory, Python/TypeScript).

2. CI on push or pull request

Run simulations on every push to main or on every pull request so each change is validated before merge. No separate schedule—the trigger is the code event.

• GitHub Actions — on: push or on: pull_request
• CircleCI — run your Okareo flow in a job that runs on every commit

This gives you continuous simulation coverage without a cron.

3. Cron + Okareo CLI

On a machine or container that has the Okareo CLI and your flow code:

1. Install the CLI and configure OKAREO_API_KEY (and any model keys).

2. Add a cron entry that runs your flow at the desired time, e.g.:

   0 2 * * * cd /path/to/project && okareo run -f my_simulation_flow

3. Optionally capture logs or exit codes to alert on failure.

Same idea works with a small script that calls the SDK instead of the CLI—run that script from cron.

What to run on a schedule

• Use a Scenario that covers your critical paths (e.g. refunds, account reset, common support intents).
• Use one or more Checks (e.g. behavior adherence, task completion) and, in CI, fail the job when a check fails so the schedule doesn’t silently regress.
• For voice, use the same Voice Simulation setup; the only change is triggering it from a scheduled job instead of the UI.

Next Steps

• Running Simulations — How runs work (rows × repeats) and UI vs SDK.
• GitHub Actions — Use the Okareo action in scheduled or push-triggered workflows.
• CircleCI — Run Okareo flows in CircleCI.
• CLI — Use okareo run in cron or scripts.