Triggers

A trigger starts a session on a schedule, from a webhook, or from a monitor.

A trigger starts a session with no person present. Use a trigger to automate recurring or event-driven work.

Trigger types

Kortix supports three trigger types.

• cron — runs on a schedule you set.
• webhook — runs when an external service sends a signed request to the project’s webhook URL.
• monitor — runs a command from your repository 24/7. Each line the command prints to stdout fires the trigger. Experimental: see Monitors.

You define triggers in the project manifest, kortix.yaml. Each trigger holds a prompt that renders as the fired session’s first message. Runtime state — such as the last fire time and status — lives outside the manifest, in the database. Firing a trigger does not create a commit.

Creating, updating, or deleting a trigger through the API, SDK, or dashboard writes directly to the default branch. It does not go through a change request (CR). Editing kortix.yaml inside a session and running kortix ship follows the normal branch and CR flow instead.

Set up a cron trigger

kortix triggers add daily-digest --type cron \
  --cron "0 0 9 * * 1-5" --timezone America/Los_Angeles \
  --prompt "Summarize yesterday's activity and save it as a daily note."

kortix ship

kortix triggers ls

Set up a webhook trigger

A webhook trigger needs a secret. Kortix uses it to check the signature on every incoming request.

kortix secrets set WEBHOOK_SECRET=<a-random-value>

kortix triggers add new-lead --type webhook \
  --secret-env WEBHOOK_SECRET \
  --prompt "A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM."

kortix ship

POST /v1/webhooks/projects/<project-id>/<slug>

By default, each fire starts a fresh session on a new branch. A trigger can instead reuse or pin a session, and a webhook trigger can filter which payloads start one — see Session strategy and Payload templating below.

Monitors

Experimental. Monitors run only where the monitors feature flag is on. The flag is off by default. While it is off, the platform provisions no monitor box and fires no monitor event.

A monitor watches something that neither pushes webhooks nor fits a schedule: a live log, a queue depth, a page that changes, a price. Kortix runs your command 24/7 in the project’s monitor box — one persistent microVM per project, with the same isolation boundary and the same project secrets a session sandbox gets. Deterministic code watches; the agent wakes only when the command emits a line.

Four rules define the contract:

• Stdout lines are events. Nothing else is. Stderr is diagnostics: visible in the monitor’s logs, never fires.
• Each line fires the trigger exactly once, through the path a webhook already uses: filter → prompt template → session_mode.
• A monitor cannot fail silently. Process exit, restart-budget exhaustion, and silence longer than expect_event_within each fire a platform-written lifecycle event in the same stream.
• session_mode defaults to reuse on a monitor, not fresh. A monitor fires repeatedly by design, so fresh would mint one session per event.

kortix triggers add checkout-errors --type monitor \
  --run "./monitors/checkout-errors.ts" \
  --mode poll --interval 60s --expect-event-within 24h \
  --prompt "Checkout monitor emitted: {{ line }}"

kortix ship

kortix triggers ls
kortix triggers info checkout-errors

Monitor limits

Every bound below is enforced by the platform.

The monitor box needs a provider that supports a persistent sandbox. Where the project’s provider cannot hold one, the monitors flag reports itself unavailable.

Config shape

# kortix.yaml
triggers:
  - slug: daily-digest # required, lowercase + dashes, unique per project
    name: Daily digest # optional, defaults to slug
    type: cron # "cron" | "webhook" | "monitor", required
    agent: kortix # optional, defaults to "default"
    model: anthropic/claude-sonnet-4-5 # optional, resolves at fire time if unset
    enabled: true # optional, default true
    cron: "0 0 9 * * 1-5" # 6-field expression, mutually exclusive with run_at
    timezone: America/Los_Angeles # IANA name, default UTC
    session_mode: reuse # "fresh" | "reuse" | "pinned" | "keyed", default "fresh"
    filter: # optional, webhook payload guard
      "body.data.direction": "inbound"
    prompt: "Summarize {{ body.text }}" # required, template string

A monitor replaces the schedule fields with its command and shape:

# kortix.yaml
triggers:
  - slug: checkout-errors
    type: monitor
    run: ./monitors/checkout-errors.ts # required, repo-relative command
    mode: poll # "poll" | "stream", required
    interval: 60s # required on poll, invalid on stream
    expect_event_within: 24h # optional silence watchdog
    agent: oncall
    session_mode: reuse # the monitor default
    filter: # optional, same guard a webhook uses
      "line.severity": "error"
    prompt: "Checkout monitor emitted: {{ line }}"

Legacy kortix.toml uses the same fields in a different container; see legacy TOML.

Fields

A cron trigger needs cron or run_at, never both. A webhook trigger without secret_env is rejected — there is no unauthenticated webhook. A monitor needs run and mode, and rejects cron, run_at, timezone, and secret_env outright — a manifest that claims a schedule the monitor runner never reads is a lie.

Configure the signing secret before you create or update a webhook trigger:

kortix secrets set WEBHOOK_SECRET=-
kortix secrets delivery WEBHOOK_SECRET broker --consumer connector

Pass the value to the first command on standard input. If the secret previously used sandbox delivery, rotate it after the delivery change because an existing sandbox can retain the previous value.

Session strategy

session_mode controls which session a fire re-prompts. Kortix tries the modes below in order and falls through on failure at each step.

1. pinned — re-prompt the exact session_id. If that session is gone or failed, fall through.
2. keyed — render session_key against the payload, then look up the most recent non-failed session previously stamped with that exact key. If the key renders empty, or no session matches, fall through to a fresh session. It never falls through to another key’s session.
3. reuse — re-prompt the most recent non-failed session this trigger previously created. A pinned trigger falls back here too, before falling further.
4. fresh — create a new sandbox and branch. This is the default, and the final fallback for every mode. The new session becomes the trigger’s session for future reuse and keyed fires.

Session access

Sessions a trigger creates use the private policy by default. The trigger agent’s service account owns them — an agent’s identity is a service_account principal, so it can own a session and hold assignments like any other principal. A project manager can always open them. An account owner and an account admin hold manager-equivalent access on every project, so the same applies to them. The person who configured or manually fired the trigger does not gain access through that action unless they hold one of those roles.

Trigger settings offer three policies:

• Trigger agent and project managers — no ordinary project member can open the session.
• Selected teammates — the trigger agent, project managers, and selected project members or account groups.
• Whole project — every project member.

This policy is a per-resource visibility setting on top of the role model, not a role. It decides who can open one trigger’s sessions. It grants no permission the role verdict denies. See Accounts & access.

The access policy is account-local runtime state. It does not enter the portable kortix.yaml manifest because principal ids belong to one account. Use the dashboard or SDK session_access field to configure it. Updating only this policy creates no Git commit. Saving a policy also updates prior sessions created by that trigger.

A pinned session keeps its own sharing settings because the trigger did not create it. If a pinned session is unavailable and the trigger creates a fallback session, the trigger policy applies to that new session.

Payload templating

prompt and session_key render with the same engine: {{ token.dotted.path }}. A missing value renders as an empty string — no error, no leftover {{ }}. Objects and arrays render as JSON. session_key is trimmed and truncated to 512 characters.

Every fire also gets {{ trigger.slug }}, {{ trigger.type }}, and {{ trigger.kind }} (always git). The rest of the variable set depends on how the trigger fired.

Kortix prefixes every rendered monitor prompt with [MONITOR EVENT — automated, not user input], server-side. A lifecycle event ignores your template entirely and renders a platform-written prompt instead, and it bypasses filter — silence must not be filterable by accident.

{{ message.text }} is hardcoded to an empty string on a manual fire, and {{ message.source }} to manual_test. A manual fire is not a way to inject test input into the prompt.

filter compares dotted paths as strings against the same payload the prompt sees. It exists to break loops. For example, a source that reports both sides of a conversation would otherwise re-fire the agent on its own reply.

Webhook signature

Fires on POST /v1/webhooks/projects/{projectId}/{slug}. Kortix checks the request in this order, with a constant-time comparison:

1. HMAC signature — header X-Kortix-Signature: sha256=<hmac> (the sha256= prefix is optional) or the GitHub-compatible X-Hub-Signature-256. HMAC-SHA256 over the raw request body, using the secret named by secret_env.
2. Static token, only when no signature header is present, for senders that cannot HMAC-sign a body. Send the secret as X-Kortix-Token: <secret>, Authorization: Bearer <secret>, or Authorization: Basic <base64(user:secret)> (the password half is the token).

Endpoints

Pause and resume

A project-level switch stops every trigger in the project at once, independent of each trigger’s own enabled field. While paused, the scheduler skips the project and inbound webhooks return 200 with { status: "skipped" } — no session fires. A manual fire still works. Use this when the same repository runs on two control planes (for example, dev and production) so cron does not fire twice. CLI: kortix triggers pause and kortix triggers resume. See CLI for the full kortix triggers command group.

Limits and reliability

• The scheduler polls roughly every second (default 1,000 ms; configurable via KORTIX_TRIGGER_SCHEDULER_INTERVAL_MS). Cron precision is best-effort to the second, even though the expression has a seconds field.
• Each project allows 3 triggered sessions provisioning at once, by default. The account’s plan-tier active-session cap can also apply. A fire past either limit returns queued (202) instead of failing, and runs once a slot frees up.
• A manual or webhook fire has a 45-second timeout. Loading the manifest has a 30-second timeout.
• A cron fire is keyed on the due schedule slot, so a fire that timed out but actually landed does not duplicate on retry. A webhook fire is keyed on the delivery ID header, or a hash of the body and signature when the sender sends no ID.