Execution and isolation
How local and cloud workflow runs execute and isolate their changes.
Every run has to execute somewhere. This page explains how cloud and local targets isolate changes, and which checkout each agent actually uses.
A fresh worktree per run
When you launch a cloud run, the runtime does not work directly in the workspace's main checkout. It mints a fresh git worktree inside the sandbox, scoped to the run. In a sequential workflow, every agent session, shell command, and file change uses that run-level worktree.
A parallel group adds a separate worktree for each lane, then merges successful lanes back into the run-level worktree before later steps continue.
This is the default for every cloud run, no setup required: launch a run and it gets its own worktree, branched off your workspace's checkout at the moment the run started.
If the runtime can't mint a worktree for a run, the run fails at that step instead of quietly falling back to your workspace's shared checkout. Isolation here is a guarantee, not a best effort: a run either gets its own checkout, or it doesn't run.
A worktree separates git changes; it is not a security boundary between agents. Agents in one run still execute under the same runtime and workflow-level tool grant.
Binding a session keeps its checkout
The one exception is a run that binds an existing live session instead of starting fresh (see Running a workflow for how binding works). A bound session already has a checkout: it is whatever target workspace it was already running in. Binding any existing session opts the run out of fresh-worktree isolation, so every slot uses that target workspace instead. A workflow with parallel groups cannot bind existing sessions.
In other words: fresh worktree is the default, and binding a session is the only thing that opts a run out of it. You made that choice already when you picked which session to hand the run.
Where a run's outputs come from
Branches, commits, and pull requests that a run's steps produce come from that run's own worktree, not from your workspace's main checkout. Two runs launched back to back against the same workspace get two separate worktrees and two separate branches. They don't collide, and neither one sees the other's uncommitted changes.
A run's worktree sticks around after the run finishes; it is not cleaned up automatically. Open session on any of the run's steps still opens the real checkout the run worked in, branch and all, even once the run is long done.
The cloud budget gate
Every cloud run passes the same budget check immediately before delivery, whether it was launched manually, from chat, on a schedule, or by a poll feed. When enforcement-mode billing says the workflow owner is over budget, the run ends as Over budget before a sandbox wakes or an agent starts. It does not retry automatically; a later launch or trigger occurrence checks again.
Local runs bypass this cloud-delivery gate because Desktop delivers them to the local runtime. Organization policies and any limits enforced elsewhere still apply.
Running on your own machine instead
A run's Run location can be On this Mac instead of the cloud (see Running a workflow). A local manual or chat launch uses the local workspace you select as-is; it does not create another worktree around that workspace.
Workflow integration grants for Issues and Slack require Cloud. A local run with one of those grants fails explicitly instead of silently omitting the tools.
Manually launched and run-from-chat local runs start immediately: the desktop app that launched the run already has the plan, and hands it straight to your local runtime. A scheduled local run uses a claim step:
- The scheduler fires the trigger on time same as a cloud schedule does, but the run it creates starts life waiting to be claimed instead of starting right away.
- Any Desktop instance signed in as the workflow owner can claim it; the claim is not bound to the device that created the schedule. After claiming, that Desktop looks for a local clone of the pinned repository. It mints a fresh worktree when the clone exists, and fails the run when it does not.
- If a claim expires before the run starts, another eligible Desktop instance can reclaim it. A run already reported as running is not automatically re-executed on another device.
For a scheduled trigger, On this Mac means "an eligible device signed in as this owner," not the specific Mac that created the schedule. Keep Desktop open on only the devices you are willing to let claim that work, and make sure each one has the pinned repository available locally.
While your laptop is closed
A due local run can wait in the cloud control plane while every eligible device is offline. Laptop sleep alone does not mark that already-created run Missed. The missed-run policy handles gaps in the scheduler's own recurrence processing; the trigger's overlap policy determines what happens to later occurrences while an earlier run is still active.
Re-attaching after you restart
After a restart, Desktop re-attaches to a non-terminal local run once the server has recorded the runtime workspace and resumes relaying its status. If the app quit after claiming but before delivery, the claim expires and another signed-in Desktop instance can claim it again.