Quickstart

Quickstart — zero to a working trigger

This page takes you from nothing to a validated, running trigger without any external service or credential, then points at the next steps. Install first (Installation — the one-liner drops the binary and seeds ~/.config/conductor/).

1. A first trigger

Replace the seeded ~/.config/conductor/config.yaml with (or just read along — the seeded starter is the same shape with a github connector):

connectors:
  timer:
    use: cron
    schedules:
      hourly: { every: 1h }

triggers:
  - name: hello
    on: [ timer.hourly, manual ]
    steps:
      - { id: say, type: command, command: [echo, "hello from conductor"] }

Three ideas in eight lines:

• Connectors are services you connect to; cron is the simplest — its declared schedule names become events (on: timer.hourly).
• on: takes a list — this trigger fires from the schedule and from the built-in manual source. A trigger with manual in its on: needs a unique name:.
• Steps do the work — here a type: command step running a local command.

2. Validate, run, fire

$ conductor validate
ok: 1 connector(s), 2 trigger(s), 0 workflow(s), 0 agent profile(s)

$ conductor run &        # start the daemon (or: conductor service install)
$ conductor run hello    # fire the manual source on demand
dispatched manual trigger "hello"

The daemon log shows the run; the schedule fires the same steps every hour. conductor validate is the contract: it resolves every on: kind, filter: key, uses: verb, option, and {{…}} reference against the connectors' published schemas before anything runs — a typo fails here, not at 3am.

Two introspection commands you will use constantly:

conductor connectors ls    # what is configured: state, events, verbs
conductor schema timer     # a connector's full contract (works on bare type names too)
conductor schema github    # every github event, filter, verb, option, output

3. Chain steps — outputs flow forward

Steps see the trigger context plus every prior step's outputs. A run: code step is the glue — reshape one step's output for the next, no external interpreter needed (js runs in a WASM sandbox inside conductor):

connectors:
  timer:
    use: cron
    schedules:
      nightly: { cron: "0 2 * * *" }

triggers:
  - name: disk-report
    on: [ timer.nightly, manual ]
    steps:
      - { id: disk, type: command, command: [df, -h, /] }
      - id: shape
        use: cli
        command: [sh]
        env: { DISK: "{{.disk.stdout}}" }
        code: |
          # stdout becomes this step's outputs, parsed as JSON.
          printf '{"summary": "%s"}' "$(printf %s "$DISK" | tail -n 1)"
      - { id: say, type: command, command: [echo, "disk: {{.shape.summary}}"] }

use: cli is conductor's one built-in engine — it runs the argv you give it with the code-step contract wrapped around it (ctx as JSON on stdin, stdout parsed into outputs), so this works on a fresh install with nothing fetched. The returned object becomes {{.shape.summary}} for the third step. conductor run disk-report fires it on demand.

Prefer writing this in JavaScript, Lua, Risor or Go? Those are engine plugins — use: js and friends work the same way, once conductor init has fetched them. See Code-Steps.

4. Where to go next

Follow the learning path on Home. The immediate next steps:

• Connect a real service — GitHub App setup: events like gh.merge_conflict / gh.failing_checks replace the cron tick, and verbs like gh.comment replace echo. Other services are in the connector catalog.

• Run an agent — add a runtimes: entry and a type: agent step (Runtimes, Steps); the seeded starter's triggers show the shape. Shared step config goes in a YAML anchor under a top-level x- key, which the loader ignores:

  runtimes:
    paseo: { use: paseo, default: true }
  x-templates:
    fixer: &fixer { type: agent, workspace: worktree, archive_when_done: true }
  triggers:
    - on: gh.merge_conflict
      steps:
        - { <<: *fixer, id: fix,
            prompt: "Resolve the conflict on {{.repo}}#{{.pr}} against {{.base}}." }

• React to the run itself — hooks: fire at start/done/fail (Workflows); post to Slack when a fix lands, page when it fails.

• Test without side effects — conductor replay <event.json> runs a saved event through the pipeline with every outbound verb stubbed (Commands).

Related: Home · Installation · Configuration · Examples