Workflows

What a workflow is

A workflow is a fixed sequence of steps that you define once and run many times. For example: plan, implement, run your checks, review, wait for your approval, then open a pull request. The steps and their order are the same on every run. AI agents do the work inside each step.

In a swarm, an orchestrator model decides the plan while it runs. In a workflow, you decide the steps in advance. Use a workflow for a process you repeat; the Swarm guide covers work where the plan should come from the goal.

Each AI step runs in an ordinary Koyd session that you can open, read, and talk to. Runs belong to the server, so closing the app does not stop them.

Build a workflow

1. Select the Workflows icon in the header and choose a project in the toolbar.
2. Choose New workflow, then Blank workflow or a template: Build feature, Fix issue, Review changes, or Quick task.
3. Give the workflow a name and, if you like, a short description.
4. Add and arrange steps on the Steps tab. On the Settings tab, set the run input, variables, workspace, schedule, and where the workflow is saved.
5. When the footer shows Ready to run, choose Save.

The YAML tab shows the same workflow as text, and edits in either view update the other. While the text is not valid YAML, the Steps and Settings tabs are unavailable. Problems appear on the step that has them, and the footer takes you there.

Good to know · The templates leave commands such as install and validate empty. Fill them in under Settings → Variables, or when you start a run. A command step whose command is empty is skipped.

Steps and their settings

Use Add step below the list, or the + between two steps to insert one there. You can move, duplicate, or delete any step. There are five kinds:

• AI step: an agent does the work in a Koyd session.
• Command: runs a shell command in the run's folder, such as your tests. A non-zero exit code fails the step. The time limit is 30 minutes unless you change it.
• Your review: pauses the run until you approve or request changes.
• Commit changes: a built-in step that commits the run's changes as logical commits.
• Change map: a built-in step that maps what the run changed. Both are described in Built-in steps below.

An AI step has Instructions, with Insert buttons for the run input, earlier steps' output, variables, the branch, and the base commit. It can also set an Agent (a saved agent brings its instructions, skills, and MCP servers), a Mode, a Model, Tools (Browser, Computer, Ask me, Helper agents), MCP servers, Skills, and Knowledge. The Ask mode is read-only: it can't edit files or run commands.

• Needs a verdict: the reply must end with VERDICT: PASS or VERDICT: NEEDS_CHANGES. Koyd asks once if the line is missing. Needs changes counts as a failure.
• Repeat until done: Koyd asks the agent to continue until a line of its reply is the finish marker you set, for up to the number of rounds you choose.
• Fresh session on retry: when the step runs again, it starts a new session instead of continuing the conversation.

Every step also sets when it Starts (After the step above, Right away, in parallel, or After specific steps) and what happens if it fails: Stop the run, Try this step again, or Go back to an earlier step, up to a number of times. The failure details go to that step as feedback, and that step and everything after it run again.

Where workflows are saved

Settings → Saved in decides where a workflow lives. Changing it moves the workflow when you save.

• Koyd: saved with your Koyd settings, like agents and swarm presets. It is available in every project on this server and is included in data export. A scheduled Koyd workflow names the project it runs in.
• Project: saved as a file in the project's .koyd/workflows folder, so you can commit it and share it with your team.

The workflow list shows both groups. A workflow's menu has Edit, Duplicate, Save to project or Move to Koyd, and Delete. The ID under Saved in is the name the command line uses, as in koyd run ID. If a project workflow and a Koyd workflow have the same ID, the command line runs the project's.

Workflows as YAML

A project workflow is a plain YAML file you can review like any other change. A short example:

name: Fix and check
isolation: worktree
input:
  label: What should be fixed?
  required: true
vars:
  validate: npm test
steps:
  - id: setup
    run: npm ci
  - id: fix
    prompt: "Fix this and add a test: {{input}}"
  - id: validate
    run: "{{vars.validate}}"
    on_fail: { goto: fix, max: 2 }
  - id: approve
    approval: Check the changes, then approve.

Every step has exactly one of prompt (AI step), run (command), approval (your review), or use (a built-in step: changemap or commit-split). AI steps also accept agent, model, reasoning, mode, tools, mcp, skills, knowledge, verdict, repeat, fresh, and timeout. A step waits for the one above it; depends_on: [] starts it right away, and a list of step IDs waits for all of them.

Prompts, commands, review messages, and built-in options can use placeholders such as {{input}}, {{vars.NAME}}, {{steps.ID.output}}, {{steps.ID.error}}, {{run.branch}}, and {{run.base}}. A command that uses an unknown vars., steps., or run. placeholder fails before it runs, so a typo does not go unnoticed.

Run a workflow

Choose Run on a workflow. Enter the input, adjust the variables under Settings for this run, and choose Start run. A command step whose command is empty once its variables are filled in is skipped.

The run view shows each step's status, attempts, duration, output, and any feedback it received. Files a step produced appear on the step: images inline, reports in a new tab, and data files as downloads. They are kept in the Koyd data folder, not in your project, and are deleted with the run. Activity lists the run's events, newest first.

Choose Open session on an AI step to read what the agent did or to talk to it. If the agent asked you a question, the step says so; answer it in the session. The run's sessions also appear in the sidebar with a workflow chip that shows the progress.

• Stop ends the running steps, including their processes and agent turns.
• Resume continues a failed or stopped run from the step that failed.
• Clean up, for a finished run on its own branch, removes the worktree and the step sessions. The branch and its commits are kept.

Run from the command line

Run these from any folder inside the project, on the computer where Koyd runs:

koyd workflows
koyd run WORKFLOW "what to do" --wait
koyd runs
koyd approve RUN_ID
koyd approve RUN_ID --reject --note "what to change"

koyd workflows lists the workflows saved in Koyd and in the project. koyd run accepts --var NAME=VALUE and --project NAME. With --wait it prints progress until the run finishes and exits with 0 on success. Without it, or if you close the terminal, the run continues on the server. koyd runs lists recent runs. koyd approve takes a run ID or the start of one; add --step STEP_ID when several reviews wait in the same run.

Good to know · The command line talks only to the local Koyd server on the same computer and user account. From other devices, use the app or the Workflow API.

Run on a schedule

Under Settings → Schedule, choose Every… (a number of minutes, hours, or days, at least 5 minutes apart) or Every day at… a time. A workflow saved in Koyd also needs the Project to run in. Set the Input for scheduled runs. Switch off Schedule on to pause the schedule without losing its settings. The workflow list shows a clock with the schedule.

• Scheduled runs start only while the server is running. Every day at… uses the server computer's local time.
• A new, changed, or re-enabled schedule waits for its next time slot.
• If the server was off when a time passed, the workflow runs once when the server is back, not once per missed time.
• A schedule never starts a second run of a workflow while an earlier run is unfinished.
• If a Koyd workflow's schedule names a project that no longer exists, the server log reports it.

Own branch or project folder

Settings → Workspace decides where the steps make their changes.

• Own branch (recommended): each run gets a new branch under koyd/ and its own Git worktree in the Koyd data folder, starting from your last commit. Your folder stays untouched, and changes you have not committed are not included.
• Project folder: the steps work directly in your project folder, alongside your other sessions. File locks coordinate supported edits there, as they do for swarms.

A new worktree has no installed dependencies, so start with an install step such as npm ci. The Build feature and Fix issue templates have one, driven by the install variable. With Project folder, the run starts from the project's current commit, so changes you had not committed yet count as the run's changes for built-in steps.

Reviews and approvals

A Your review step pauses the run until you decide. When you add one after an AI step, Request changes sends your note back to that step, up to 3 times. Change this under If you request changes.

The run view then opens with Your review is needed at the top: your message, the branch the changes are on, and What to review, which lists the results of the steps before it with their output, files, and Open session. Choose Approve, or write a note and choose Request changes. A review with no route back offers Reject instead, which stops the run. After you decide, Koyd opens the next waiting review, so you can go through several in a row.

A waiting review shows up in several places:

• Waiting for you, at the top of the Workflows view, lists every waiting review from every project and run, oldest first.
• The Workflows icon in the header shows how many reviews are waiting. Selecting it opens the oldest one.
• The installed app's icon shows the same count, where the system supports app badges.
• The run's sessions in the sidebar show a review chip.
• A notice appears when a new review starts waiting while you are elsewhere in Koyd, unless the device gets notifications.

To get a notification on your phone or computer, even when Koyd is closed, choose Turn on notifications in the Workflows view or use the bell in the Workflows toolbar. Koyd also offers it when you start a workflow that has a review. Tapping a notification opens that review. iPhone and iPad need iOS 16.4 or later with Koyd added to the Home Screen, and the server needs internet access because notifications go through the browser's push service. Your workspace across devices lists every requirement.

Good to know · A decision for a review that was replaced by a newer one, for example after the steps before it ran again, is refused, so you never approve something you did not see. You can review from any paired device, including your phone, or with koyd approve.

Built-in steps

Two steps built into Koyd turn a run's work into something easy to review and ship. They need the run folder to be a Git repository. A built-in step can wait for you too; it then appears with the other reviews.

Change map turns what the run changed, its commits and its uncommitted changes, into a code map. It makes an overview image (SVG by default; PNG needs the bundled browser) and an interactive report where every element opens its diff, and saves the map in the project's Codemaps. The step shows the totals with Open report and Open in Code maps. Options: Title, Focus, Overview image, Interactive report, Save as a code map, Files to map (200 by default), and Model. Running the step again replaces its map instead of adding another, and a run without changes skips it.

Later steps can insert the path of the image or report, for example to attach the image to a pull request. Code maps, memory, and context explains how a change map looks in the explorer.

Commit changes splits the run's uncommitted changes into logical commits with the commit-message model from settings, or the Model you choose. Only these files limits it to matching paths, such as src/**, and Commit message instructions adds guidance, such as a ticket prefix. With Review the commits first, the run waits and shows the proposed commits. Edit messages, move files between commits, or add a New commit, then choose Commit. Or describe what should change and choose Request a new plan.

From the command line, koyd runs and koyd run --wait list the proposed commits, and koyd approve RUN_ID --plan plan.json commits an edited plan.

Good to know · Commit changes never pushes, amends, or rewrites commits. It refuses to commit when the folder has merge conflicts or a merge, rebase, cherry-pick, or revert in progress. Koyd makes the commits with its built-in Git, so Git hooks do not run and commits are not signed; the step logs a warning when the repository uses hooks or signing. After 5 new plans, another request for changes fails the step.

Create workflows from chat

Start a session in the Koyd Manager mode and describe the workflow you want, or ask it to change an existing one, saved in Koyd or in a project. It checks the workflow with the same rules as the editor before saving and says in the chat what it saved. Open the workflow in the editor to check its steps before the first run.

Your own app: Workflow API and SDK

The Workflow API lets your own app or dashboard start the workflows you allow, follow every step live (agent text, tool calls, and command output), and answer reviews over HTTPS. Webhooks can notify another server of run events. The API lives under /api/v1 on your Koyd address, and /api/v1/openapi.json describes it.

Create a scoped API key on the computer running Koyd. The secret is shown once.

koyd api-keys create dashboard --scope workflows:read --scope workflows:run --scope workflows:approve --workflow build-feature

The scopes are workflows:read, workflows:run, workflows:approve, workflows:manage, and webhooks:manage. --workflow and --project limit what a key can see, --origin lets a browser page on that origin call Koyd directly, and --expires ends the key after a time or on a date. koyd api-keys list shows your keys, and koyd api-keys revoke ID removes one.

For TypeScript, the @koyd/workflows SDK wraps the API with typed calls, live event streams that reconnect and resume on their own, and webhook signature checks. It runs in browsers and Node 18 or later. An example dashboard shows a complete custom UI that keeps the key on its own server.

Good to know · workflows:manage is high trust: a workflow's command steps run as shell commands on the Koyd computer whenever the workflow runs. Keep API keys on your backend rather than in a web page, and give each key only the scopes, workflows, and projects it needs.

Reliability and limits

• Run state is saved to disk. After a restart, a step that was waiting for an agent picks up again without sending the prompt twice, and an interrupted agent turn is asked once to check the current state and continue. Reviews keep waiting.
• An interrupted command step runs again from the start, so write commands that are safe to repeat.
• An agent turn that runs longer than the step's timeout, 240 minutes unless you set timeout in the YAML, is stopped and the step fails.
• If a step fails and has no route back left, the run fails and steps still running in parallel are stopped.
• The step order is the same on every run. What the models produce inside each step is not, so choose models and checks you can rely on.

Good to know · Commands run with your own permissions, as they would in a terminal. Only run workflows from people you trust, and read the commands in someone else's workflow before you run it. The Ask mode and read-only saved agents cannot edit files or run commands, but a reviewer that needs git diff has to run in a writable mode. Telling it not to edit files is an instruction, not a sandbox.

A step can send a message through an MCP server you add under Lab → MCP Servers, for example a messaging server. Answering a review by replying in that chat, and starting runs from GitHub or chat events, are not available. Answer reviews in Koyd, with koyd approve, or through the API.