Trigger Types Reference

Overview

Fleet supports seven trigger types for automating agent execution. Each trigger type responds to different events—from cron schedules to git commits to file changes.

Type	Description	Interactive
Schedule	Cron-based scheduling	No
Webhook	HTTP POST from external services	Yes
File Watcher	Respond to filesystem changes	No
Daemon	Continuous script with event output	No
Git Hook	Git repository events	Depends
CLI	Command-line invocation	Yes
MCP	Invoked from MCP servers	Yes

Interactive triggers have a user present who can respond to approval requests. Non-interactive triggers run autonomously and must have pre-approved permissions.

---

Schedule

Cron-based triggers that run on a defined schedule.

Configuration

name: daily-report
type: schedule
cron: "0 9 * * 1-5"  # 9 AM on weekdays
enabled: true

Field	Type	Required	Description
name	string	Yes	Unique trigger identifier
type	string	Yes	Must be schedule
cron	string	Yes	Cron expression (5 or 6 fields)
enabled	boolean	No	Whether trigger is active (default: true)

Cron Expression Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common patterns:

Expression	Description
0 9 * * *	Every day at 9:00 AM
0 9 * * 1-5	Weekdays at 9:00 AM
*/15 * * * *	Every 15 minutes
0 0 1 * *	First of every month at midnight
0 */4 * * *	Every 4 hours

Example: Weekly Summary

name: weekly-summary
type: schedule
cron: "0 9 * * 1"  # Monday at 9 AM

Agent binding in AGENT.md:

triggers:
  - trigger: weekly-summary
    enabled: true

---

Webhook

Receive HTTP POST requests from external services.

Requires Fleet Gateway — Connect at Settings → Remote.

Configuration

name: github-events
type: webhook
require_signature: true
enabled: true

Field	Type	Required	Description
name	string	Yes	Unique trigger identifier
type	string	Yes	Must be webhook
require_signature	boolean	No	Require HMAC signature verification
webhook_url	string	Auto	Generated URL from Fleet Gateway
gateway_trigger_id	string	Auto	ID on Fleet Gateway
enabled	boolean	No	Whether trigger is active (default: true)

Creating Webhooks

Ask an agent to create a webhook:

Create a webhook for GitHub events

The agent calls create_webhook(name: "github-events") and returns a URL like:

https://fleet-gateway.fly.dev/t/abc123xyz

Provide this URL to the external service.

Signature Verification

For security, enable signature verification:

require_signature: true

Fleet generates a signing secret (stored in Keychain). Configure the external service to sign payloads with this secret.

GitHub: Uses X-Hub-Signature-256 header with HMAC-SHA256.

Webhook Payload

The webhook body is available in agent bindings:

triggers:
  - trigger: webhook:github-events
    params:
      action: "{{body.action}}"
      repo: "{{body.repository.full_name}}"
      pr_number: "{{body.pull_request.number}}"

Common Integrations

GitHub:

1. Repository → Settings → Webhooks → Add webhook
2. Paste the webhook URL
3. Select events (push, pull_request, issues, etc.)
4. Enable signature and add the secret

Stripe:

1. Dashboard → Developers → Webhooks → Add endpoint
2. Paste the webhook URL
3. Select events
4. Copy signing secret to Fleet Vault

Slack:

1. api.slack.com → Create app
2. Event Subscriptions → Enable
3. Request URL → Paste webhook URL

---

File Watcher

Trigger when files change in watched directories.

Configuration

name: inbox-watcher
type: file_watcher
watch_paths:
  - ~/inbox
  - ~/Documents/*.pdf
enabled: true

Field	Type	Required	Description
name	string	Yes	Unique trigger identifier
type	string	Yes	Must be file_watcher
watch_paths	string[]	Yes	Paths/glob patterns to watch
enabled	boolean	No	Whether trigger is active (default: true)

Watch Paths

Supports glob patterns:

Pattern	Matches
~/inbox	All changes in ~/inbox directory
~/Documents/*.pdf	PDF files in Documents
/var/log/**/*.log	Log files anywhere in /var/log

Cooldown

File watchers have a built-in cooldown to prevent rapid-fire triggering from multiple quick saves.

Example: Auto-Process Downloads

name: download-processor
type: file_watcher
watch_paths:
  - ~/Downloads/*.pdf
  - ~/Downloads/*.csv

Agent binding:

triggers:
  - trigger: download-processor
    enabled: true

Prompt template:

A new file was downloaded: {{output}}.
Analyze its contents and move it to the appropriate folder.

---

Daemon

Continuously running scripts that output events.

Configuration

name: log-monitor
type: daemon
script: |
  tail -F /var/log/app.log | grep --line-buffered "ERROR"
enabled: true

Field	Type	Required	Description
name	string	Yes	Unique trigger identifier
type	string	Yes	Must be daemon
script	string	Yes	Bash script to run continuously
enabled	boolean	No	Whether trigger is active (default: true)

How Daemons Work

1. Fleet starts the script as a background process
2. Each line of stdout triggers the subscribed agents
3. If the script exits, Fleet restarts it automatically
4. Built-in cooldown prevents overwhelming agents

Cooldown

Daemons have a configurable cooldown (minimum 1 second) between triggers to prevent flooding.

Example: Error Monitor

name: error-monitor
type: daemon
script: |
  tail -F /var/log/myapp/error.log | while read line; do
    echo "$line"
  done

Example: API Status Checker

name: api-health
type: daemon
script: |
  while true; do
    status=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health)
    if [ "$status" != "200" ]; then
      echo "API unhealthy: $status"
    fi
    sleep 60
  done

---

Git Hook

Trigger on git repository events like commits, pushes, and merges.

Configuration

name: pre-commit-lint
type: git_hook
git_hook_type: pre-commit
repo_paths:
  - ~/projects/my-app
pass_context: true
enabled: true

Field	Type	Required	Description
name	string	Yes	Unique trigger identifier
type	string	Yes	Must be git_hook
git_hook_type	string	Yes	Type of git hook (see below)
repo_paths	string[]	Yes	Repositories where hook is installed
pass_context	boolean	No	Include git context in trigger payload
enabled	boolean	No	Whether trigger is active (default: true)

Git Hook Types

Hook Type	When It Runs	Blocking
pre-commit	Before commit is created	Yes
commit-msg	After commit message is written	Yes
prepare-commit-msg	Before commit message editor opens	Yes
pre-push	Before push to remote	Yes
pre-rebase	Before rebase starts	Yes
post-commit	After commit is created	No
post-merge	After merge completes	No
post-checkout	After checkout completes	No
post-rewrite	After commits are rewritten (rebase/amend)	No

Blocking hooks are interactive—the user is waiting at the terminal. The agent can:

• Allow the operation (exit 0)
• Block the operation (exit 1)
• Request changes from the user

Non-blocking hooks run in the background after the operation completes.

Git Context

When pass_context: true, the trigger payload includes:

Field	Description
changed_files	List of files changed
commit_msg	Commit message (for commit hooks)
branch	Current branch name
remote	Remote name (for push hooks)
ref	Reference being pushed/checked out

Example: Pre-Commit Linting

name: lint-check
type: git_hook
git_hook_type: pre-commit
repo_paths:
  - ~/projects/my-app
pass_context: true

Agent binding:

triggers:
  - trigger: lint-check
    enabled: true

The agent receives changed files and can run linters, returning exit code 0 to allow or 1 to block.

Example: Post-Commit Documentation

name: update-docs
type: git_hook
git_hook_type: post-commit
repo_paths:
  - ~/projects/my-app
pass_context: true

Agent can automatically update documentation after commits.

---

CLI

Built-in trigger for command-line invocation.

Usage

fleet run <agent-name> [--param key=value...]

Parameters

Pass parameters on the command line:

fleet run code-reviewer --param file_path=./src --param focus=security

Parameters are matched against the agent's parameters definition in AGENT.md.

Example

Agent definition:

name: code-reviewer
parameters:
  - name: file_path
    type: path
    required: true
  - name: focus
    type: string
    default: all

Invocation:

fleet run code-reviewer --param file_path=./src/api

---

MCP

Built-in trigger for invocation from MCP (Model Context Protocol) servers.

When Fleet runs as an MCP server, other applications can invoke agents through the MCP protocol.

Usage

Start Fleet as an MCP server:

fleet mcp

Other MCP clients can then invoke agents as tools.

Agent as MCP Tool

Each agent becomes an MCP tool with:

• Name: Agent name (e.g., code-reviewer)
• Description: Agent description
• Parameters: Agent's parameter definitions

---

Trigger Payload Structure

All triggers produce a payload that's passed to the agent:

{
  "trigger_id": "abc123",
  "trigger_type": "webhook",
  "source": "github-events",
  "data": {
    "action": "opened",
    "pull_request": { ... }
  },
  "output": "Raw trigger output",
  "prompt": "Processed prompt template"
}

Field	Description
trigger_id	Unique identifier for this trigger event
trigger_type	Type of trigger (schedule, webhook, etc.)
source	Trigger name
data	Structured data (webhook body, git context, etc.)
output	Raw output (script stdout, webhook body as string)
prompt	Processed prompt template with substitutions

Template Substitution

Use {{output}} in prompt templates to include trigger output:

triggers:
  - trigger: file-watcher
    prompt_template: "New file detected: {{output}}. Process it."

For webhooks, access structured fields:

triggers:
  - trigger: webhook:github-events
    params:
      action: "{{body.action}}"
      repo: "{{body.repository.name}}"

---

Interactive vs Non-Interactive

Interactive triggers (cli, webhook, mcp, blocking git_hook):

• User is present and can respond to prompts
• Can request tool approvals
• Can ask clarifying questions

Non-interactive triggers (schedule, file_watcher, daemon, non-blocking git_hook):

• Run autonomously without user interaction
• Must have all permissions pre-approved
• Cannot request user input

For non-interactive triggers, ensure the agent has:

• Appropriate execution tier
• Pre-approved permission rules
• Access to required secrets

---

Next Steps

• Create trigger automations
• Configure agent trigger bindings
• Manage triggers in Settings