opensource/kilocode
3
0
Fork 0
mirror of https://github.com/Kilo-Org/kilocode.git synced 2026-08-28 19:11:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add scheduled triggers documentation

Browse Source
This commit is contained in:
St0rmz1
2026-04-03 07:52:31 -07:00
parent 4bebc24e4e
commit 6fba6179d7
5 changed files with 174 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/kilo-docs/lib/nav/kiloclaw.ts
+1
View File
@@ -43,6 +43,7 @@ export const KiloClawNav: NavSection[] = [
subLinks: [
{ href: "/kiloclaw/triggers", children: "Overview" },
{ href: "/kiloclaw/triggers/webhooks", children: "Webhooks" },
{ href: "/kiloclaw/triggers/scheduled", children: "Scheduled" },
],
},
{
packages/kilo-docs/pages/code-with-ai/platforms/cloud-agent.md
+33 -13
View File
@@ -112,30 +112,43 @@ Cloud Agents are great for:
- **Automated refactors or tech debt cleanup** driven by Kilo Code
- **Offloading CI-like tasks**, experiments, or batch updates
## Webhook Triggers
## Triggers
Webhook triggers allow you to initiate cloud agent sessions via HTTP requests. This enables integration with external services and automation workflows.
Triggers allow you to initiate cloud agent sessions automatically, either via HTTP requests (webhooks) or on a recurring schedule. This enables integration with external services and time-based automation workflows.
{% callout type="note" %}
Webhook triggers are currently in beta and subject to change.
Triggers are currently in beta and subject to change.
{% /callout %}
### Accessing Webhooks
### Accessing Triggers
Webhook triggers are accessible from the main sidebar with an entry named **Webhook** and link to [https://app.kilo.ai/cloud/webhooks](https://app.kilo.ai/cloud/webhooks) for personal accounts. Organization-level webhook configurations are available through your organization's sidebar.
Triggers are accessible from the main sidebar under **Webhooks / Triggers** and link to [https://app.kilo.ai/cloud/triggers](https://app.kilo.ai/cloud/triggers) for personal accounts. Organization-level trigger configurations are available through your organization's sidebar.
### Activation Modes
When creating a trigger, you choose an **activation mode** that cannot be changed after creation:
- **Webhook**: Fires when an external service sends an HTTP request to the trigger's URL
- **Scheduled**: Fires on a recurring schedule defined by a cron expression
### Configuration
Webhook triggers utilize [agent environment profiles](#agent-environment-profiles) to configure the execution environment for triggered sessions. The agent resolves the profile at runtime, so profile updates apply automatically to future executions. Profiles referenced by triggers cannot be deleted until those triggers are updated or removed.
Triggers utilize [agent environment profiles](#agent-environment-profiles) to configure the execution environment for triggered sessions. The agent resolves the profile at runtime, so profile updates apply automatically to future executions. Profiles referenced by triggers cannot be deleted until those triggers are updated or removed.
Webhook triggers do not support manual env var or setup command overrides at this time.
Triggers do not support manual env var or setup command overrides at this time.
### Scheduled Triggers
Scheduled triggers fire on a recurring schedule using cron expressions. You can configure them with a simple frequency picker (every 10 minutes, hourly, daily, weekly) or enter a raw cron expression for full control. Each trigger has a configurable timezone (default: UTC) and handles daylight saving time transitions automatically.
The minimum schedule interval is 10 minutes. Scheduled triggers use `{{scheduledTime}}` and `{{timestamp}}` as prompt template variables (webhook-specific variables like `{{body}}` are not available since there is no inbound HTTP request).
### Trigger Limits and Guidance
Webhook triggers are designed for low-volume invocations from trusted sources and are best suited for short-lived tasks.
Triggers are designed for low-volume invocations from trusted sources and are best suited for short-lived tasks.
- **Personal webhooks**: Execute in the same sandbox container as a user's Cloud Agent sessions. You can view/join invocations live.
- **Organization webhooks**: Execute in dedicated compute resources as a bot user, similar to Code Review sessions. You can share/fork the sessions when they're complete.
- **Personal triggers**: Execute in the same sandbox container as a user's Cloud Agent sessions. You can view/join invocations live.
- **Organization triggers**: Execute in dedicated compute resources as a bot user, similar to Code Review sessions. You can share/fork the sessions when they're complete.
Additional limits:
@@ -144,11 +157,13 @@ Additional limits:
- **Retention**: only the **most recent 100 requests per trigger** are retained
- **In-flight cap**: at most **20 requests per trigger** can be in `captured` or `inprogress` at once (returns `429`)
The webhook endpoint will return rate limit responses when the number of queued or processing requests exceeds system capacity.
The trigger endpoint will return rate limit responses when the number of queued or processing requests exceeds system capacity.
### Webhook Prompt Template Variables
### Prompt Template Variables
You can reference request data in a trigger’s prompt template using these placeholders:
You can reference data in a trigger’s prompt template using these placeholders.
**Webhook triggers:**
- `{{body}}` - raw request body (string)
- `{{bodyJson}}` - pretty-printed JSON if parseable, otherwise raw body
@@ -159,6 +174,11 @@ You can reference request data in a trigger’s prompt template using these plac
- `{{sourceIp}}` - client IP if provided (falls back to `unknown`)
- `{{timestamp}}` - capture timestamp (ISO string)
**Scheduled triggers:**
- `{{scheduledTime}}` - the time the schedule fired (ISO string)
- `{{timestamp}}` - capture timestamp (ISO string)
{% callout type="warning" title="Security Considerations" %}
Care should be taken when deciding to use webhooks as they are susceptible to prompt injection attacks. Especially in scenarios where webhook payloads may contain untrusted input. At this time we recommend using webhooks only for trusted sources.
{% /callout %}
packages/kilo-docs/pages/kiloclaw/triggers/index.md
+14 -9
View File
@@ -7,26 +7,31 @@ description: "Automate your KiloClaw agent with webhooks and scheduled triggers"
Triggers let external events and schedules drive your KiloClaw agent automatically. Instead of typing every instruction yourself, triggers deliver messages to your agent on your behalf. This lets it react to real-world events or run tasks on a schedule without polling.
All triggers are managed from the **Settings** tab on your [KiloClaw dashboard](/docs/kiloclaw/dashboard).
All triggers are managed from the **Settings** page in the KiloClaw section of the sidebar.
## Trigger Types
| Type | Description | Status |
| --- | --- | --- |
| [**Webhooks**](/docs/kiloclaw/triggers/webhooks) | Receive HTTP requests from external services (GitHub, Stripe, monitoring tools, etc.) and deliver them as chat messages to your agent | Available |
| **Time-based** | Run tasks on a schedule using cron expressions | Coming soon |
| Type | Description |
| --- | --- |
| [**Webhooks**](/docs/kiloclaw/triggers/webhooks) | Receive HTTP requests from external services (GitHub, Stripe, monitoring tools, etc.) and deliver them as chat messages to your agent |
| [**Scheduled**](/docs/kiloclaw/triggers/scheduled) | Run tasks on a recurring schedule (e.g. every 15 minutes, daily at 9 AM, weekdays only) |
## How Triggers Work
1. An event occurs (an HTTP request arrives, or a schedule fires)
2. The trigger validates the request and renders the payload through a **prompt template**
3. The rendered message is delivered to your KiloClaw instance as a chat message
1. A trigger fires
2. Your **prompt template** is rendered into a message
3. That message is delivered to your KiloClaw instance as a chat message
4. Your agent processes and responds like any other conversation
Prompt templates give you control over how payloads are presented to your agent. You can include instructions, context, and formatting alongside the raw event data.
Each trigger type has its own set of template variables. See the [Webhooks](/docs/kiloclaw/triggers/webhooks) and [Scheduled](/docs/kiloclaw/triggers/scheduled) pages for details.
{% callout type="warning" title="Triggers send prompts directly to your agent" %}
When a trigger fires, the rendered message is sent directly to your KiloClaw agent as a prompt. If your instance is configured with a permission model that allows all actions, the agent will execute commands automatically without your explicit approval. This means triggers can cause your agent to take actions without you being aware. Review your instance's [permission settings](/docs/kiloclaw/control-ui/exec-approvals) and prompt templates carefully before enabling triggers.
{% /callout %}
## Related
- [Webhooks](/docs/kiloclaw/triggers/webhooks)
- [Scheduled Triggers](/docs/kiloclaw/triggers/scheduled)
- [KiloClaw Overview](/docs/kiloclaw/overview)
- [Dashboard Reference](/docs/kiloclaw/dashboard)
packages/kilo-docs/pages/kiloclaw/triggers/scheduled.md
+123
View File
@@ -0,0 +1,123 @@
---
title: "Scheduled Triggers"
description: "Run tasks on a schedule using cron expressions"
---
# Scheduled Triggers
Scheduled triggers let your KiloClaw agent run tasks automatically on a recurring schedule. Instead of waiting for an external event, a scheduled trigger fires at the times you define using cron expressions. When it fires, the prompt template is rendered and delivered as a chat message to your KiloClaw instance, just like a webhook.
## Setup
1. Go to **Settings** under the KiloClaw section in the sidebar
2. Find the **Scheduled Triggers** section and click **Add Scheduled Trigger**
3. Give your trigger a name (minimum 8 characters)
4. Configure the schedule and prompt template
5. Click **Save**
Each KiloClaw instance supports up to **5 scheduled triggers** alongside its single webhook.
## Configuring a Schedule
The schedule builder defaults to a friendly picker view. For more control, click **<> Advanced** to switch to raw cron input.
### Simple Mode (default)
Pick a frequency, time, and (optionally) days of the week from dropdown menus. The builder generates the cron expression for you behind the scenes and shows a preview of the next 5 upcoming runs.
- **Repeat**: Every 10 minutes, every 15 minutes, every 30 minutes, hourly, daily, weekly
- **At**: Select the time of day (for daily and weekly frequencies)
- **Day of week**: Select which days the trigger should fire (for weekly frequency)
### Advanced Mode
Click **<> Advanced** to enter a raw cron expression directly. This gives you full control over the schedule. The expression is validated in real time with a preview of upcoming fire times.
Cron expressions use the standard five-field format:
```
┌───────── minute (0-59)
│ ┌───────── hour (0-23)
│ │ ┌───────── day of month (1-31)
│ │ │ ┌───────── month (1-12)
│ │ │ │ ┌───────── day of week (0-7, where 0 and 7 are Sunday)
│ │ │ │ │
* * * * *
```
**Examples:**
| Expression | Meaning |
| --- | --- |
| `*/15 * * * *` | Every 15 minutes |
| `0 9 * * 1-5` | 9:00 AM on weekdays |
| `0 0 1 * *` | Midnight on the first of each month |
| `30 14 * * 3` | 2:30 PM every Wednesday |
{% callout type="note" title="Minimum interval" %}
The minimum interval between scheduled trigger runs is 10 minutes. Schedules more frequent than that are rejected.
{% /callout %}
### Timezone
Select a timezone for your schedule. The default is UTC. All fire times are calculated relative to the selected timezone, including automatic handling of daylight saving time transitions.
## Prompt Template
The prompt template controls what message your agent receives when the schedule fires. You can customize it from the trigger's settings.
**Default template:**
```
Run your scheduled task. Triggered at {{scheduledTime}}.
```
**Available variables:**
| Variable | Description |
| --- | --- |
| `{{scheduledTime}}` | The time the schedule fired (ISO string) |
| `{{timestamp}}` | Capture timestamp (ISO string) |
{% callout type="note" title="Webhook variables are not available" %}
Since scheduled triggers do not receive an HTTP request, variables like `{{body}}`, `{{bodyJson}}`, `{{headers}}`, `{{method}}`, `{{path}}`, and `{{query}}` are not populated. Use `{{scheduledTime}}` and `{{timestamp}}` instead.
{% /callout %}
## Managing Scheduled Triggers
### Pause and Resume
Toggle the **Active/Paused** switch to temporarily stop a trigger from firing. When paused, the schedule is suspended but the configuration is preserved. Resume at any time to restart the schedule.
### Edit
You can update the cron expression, timezone, and prompt template of an existing scheduled trigger at any time. The activation mode (webhook vs. scheduled) cannot be changed after creation.
### Delete
Remove a scheduled trigger from the inline controls in the Settings panel. A confirmation dialog is shown before deletion.
## Viewing Scheduled Trigger Activity
Scheduled trigger invocations appear in the same request history as webhooks. The **Source** column shows a **Scheduled** badge to distinguish them from webhook-triggered requests. Click into a request to see the scheduled fire time and other details.
## Example: Daily Standup Summary
Create a scheduled trigger that fires every weekday morning and asks your agent to summarize overnight activity:
1. Add a scheduled trigger in your KiloClaw Settings
2. Set the frequency to **Daily** at **9:00 AM** in your local timezone
3. Customize the prompt template:
```
Good morning! Please summarize any overnight activity in the #engineering Slack channel and list open pull requests that need review today. Triggered at {{scheduledTime}}.
```
Your agent will receive this message every weekday at 9:00 AM and respond with the summary.
## Related
- [Webhooks](/docs/kiloclaw/triggers/webhooks)
- [Triggers Overview](/docs/kiloclaw/triggers)
- [KiloClaw Overview](/docs/kiloclaw/overview)
- [Dashboard Reference](/docs/kiloclaw/dashboard)
packages/kilo-docs/pages/kiloclaw/triggers/webhooks.md
+3 -1
View File
@@ -9,7 +9,7 @@ KiloClaw supports inbound webhooks so external events can trigger your agent aut
## Setup
1. Go to the **Settings** tab on your [KiloClaw dashboard](/docs/kiloclaw/dashboard)
1. Go to **Settings** under the KiloClaw section in the sidebar
2. Find the **Webhook Integration** card and click **Manage**
3. Click **Set Up Webhook**
@@ -104,6 +104,8 @@ Now every push to that repository sends a payload to your agent. Customize the p
## Related
- [Scheduled Triggers](/docs/kiloclaw/triggers/scheduled)
- [Triggers Overview](/docs/kiloclaw/triggers)
- [KiloClaw Overview](/docs/kiloclaw/overview)
- [Dashboard Reference](/docs/kiloclaw/dashboard)
- [GitHub Integration](/docs/kiloclaw/development-tools/github)