How and where phases run
What physically executes a phase, and how AgentSDE decides which machine that execution lands on. This is the runtime model underneath every run · one level below the runtime how-to, so you can reason about where your code runs and what stays true no matter where it lands.
#A phase is an isolated unit of execution
When a phase runs, one thing happens: the model named on that phase is invoked under the phase’s system prompt, with only the tools the phase allows, inside a sandboxed workspace, on the agent’s own branch. That bundle · model, prompt, allowed tools, workspace, branch · is the whole unit. Nothing outside it leaks in, and the phase cannot reach past it.
This is the same bounded invocation described in how a run executes. What this page adds is the next question: once AgentSDE has a phase to run, whose hardware actually runs it?
#Two runtimes, one behaviour
A phase can execute in one of two places, and you choose which for the workspace in Settings → Runtime:
- AgentSDE Cloud · phases run on AgentSDE’s managed servers. There is nothing to install and nothing to keep online. This is the default, and for most teams it is the only setting they ever touch.
- Your own machine · phases run on a device you control, reached through the AgentSDE Connect daemon. You pair the machine once at
/connect, and after that it just needs to be online.
The important part is what does not change between them. Same phases, same prompts, same allowed tools, same artefacts, same guarantees. An agent behaves identically on cloud or on your own machine · only the location of execution differs.
Switching runtimes never edits your phases, prompts or triggers. It changes whose hardware and credentials a phase runs on, and nothing else about how the run behaves.
#What the Connect daemon is
The Connect daemon is a small program you install on a machine you own · a laptop, a build box, a server. Once it is signed in to your workspace it behaves like a self-hosted runner: it sits idle waiting for work, and when AgentSDE has a phase to run it hands the phase to the daemon instead of running it in the cloud. The daemon clones the repository locally, runs the phase on that box, and reports logs, artefacts and token usage back.
Because the daemon runs where you put it, everything a phase touches · the checkout, the shell, the toolchain, the network, the model call · is your machine’s, not AgentSDE’s. AgentSDE orchestrates the run but never holds the working copy. Pairing happens once at /connect; see Devices and API keys for the full flow.
#How a phase is dispatched to a runner
Dispatch is a placement decision made per phase, the moment AgentSDE has work to run:
- A run configured for AgentSDE Cloud executes on managed infrastructure. There is no device to reach, so placement is immediate.
- A run configured for your own machine is dispatched to the paired device when its daemon is online. The phase runs there, and results flow back to the workspace.
#When no device is online
Your own machine can be offline · the daemon isn’t running, the laptop is asleep, or its access has lapsed. Because a phase can arrive at any moment, you tell AgentSDE ahead of time what to do when it has work but no device to give it. There is a single no-device-online fallback, with two settings:
- Fall back to AgentSDE Cloud · if no device is online, the phase runs in the cloud instead of waiting. Nothing stalls · this is the recommended choice.
- Require my machine · pause · the phase waits instead of running in the cloud. It starts the moment a device connects with valid access.
The fallback applies whenever the device is offline, lapsed, or busy. It only exists when you have chosen your own machine, since cloud has nothing to fall back to. This is the honest trade behind the two runtimes: cloud is always there, your own machine is only there when the daemon is running, and the fallback is how you decide what “no machine right now” should mean.
#What a self-hosted runner gives you
The reason to run on your own machine is containment. When a phase executes through the daemon, your code, your credentials and the model calls stay on hardware you control · nothing about the run leaves the machine except the results you would see anyway. If policy requires runs on your own hardware, or you need a specific local toolchain, this is the runtime that delivers it.
#What holds either way
Where a phase runs changes who owns the hardware. It does not change what a phase is allowed to do. These guarantees are enforced by the runtime wherever the phase executes:
- The allowed-tools list is enforced at execution. A phase can only use the tools its design grants it, cloud or self-hosted alike. A phase cannot reach for a tool it was not given · the grant is a ceiling, not a suggestion.
- Writes stay on the agent’s own branch. The agent reads the code and makes its changes on its own branch, never directly on yours. When the pipeline reaches a delivery phase it opens a pull request from that branch, and your branch protection decides the rest. There is no path by which a run merges to a protected branch or relaxes a rule · that stays with your reviewers and checks.
- The same result surfaces. Every phase leaves an artefact you can read on the run detail, and cost accrues phase by phase, no matter which runtime produced the work.
An agent is a contributor, not an administrator, and moving it onto your own machine does not widen what it may do. A self-hosted run gains you privacy over the where; it grants no extra authority over the what.
#Where to go next
- Runtime · choose the runtime for your workspace, manage the paired device, and set the fallback.
- Devices and API keys · pair a machine at
/connectand read the scope model behind a device. - How a run executes · the mechanical model for what a run does between an issue arriving and a pull request opening.