Tutorial
Run a Safe Local and Cloud Agent Mix
Pro, about 45 minutes. Decide which automated coding jobs belong in the cloud, set up both tracks, and hand a job off without leaking a secret or stranding the work.
Oct 31, 2026 - 11 min read
What You Will Build
A routing discipline for a team that runs automated coding jobs - the kind where an agent, not a person, opens the branch - split cleanly across two tracks. By the end you will have a short inventory of your jobs, a six-question test that marks each one as cloud-eligible or not, a cloud environment set up so secrets never enter it, and a start-watch-fetch loop that treats a cloud job as fire-and-forget. You will also have a single revertible flag per job, so flipping one back to local is one change.
This is not a toy. It is the exact set of decisions I had to make before I would let a free cloud credit anywhere near my build pipeline.
Prerequisites
- An account on a coding-agent platform that offers cloud sessions (this walkthrough uses Claude Code's terms; Codex, Copilot, Jules, Cursor and others follow the same shape).
- A job runner you control: the script or service that launches your automated coding jobs today.
- Git with a remote you can push to, and the platform's Git app or proxy connected to the repositories you care about.
- Admin rights to enable cloud sessions for your organisation, if your platform gates them behind a policy.
Tip
Before you touch any configuration, write down how your runner decides a job is "done" today. Almost every local runner waits for a process to end and reads what it printed. That single assumption is the thing a cloud job breaks, and knowing it up front saves you the afternoon I lost.
Mental Model
The same agent runs two ways. Hands-on, it runs on your own machine and sees the whole disk - every repository, your shared folders, your local services and secrets - and a command waits until it finishes. Hand-off, it runs in an isolated cloud machine that holds one repository cloned from Git, cannot see anything else on your disk, and returns a pushed branch or a pull request.
The trap is that the two look identical until you automate them. A hands-on start blocks and prints its result. A hand-off start returns almost immediately with a session id and runs on in the background, and there is no status command that blocks and hands you the transcript. So you do not wait for a cloud job. You record its id, watch Git for the branch, then fetch and review. Routing a job to the wrong track is not a style choice; a job that needs your disk simply cannot run in the cloud, and a runner that waits on a cloud job hangs forever.
Steps
Inventory every automated coding job
List every job your agents run without a human in the loop. For each one, write down four things: which repositories it touches, what "done" actually means (a merged pull request, a built file, a passing check on your own machine), whether it produces an artifact that has to land on disk, and whether any step needs a specific machine.
Keep it in something you can diff later. A flat file is enough:
jobs:
- name: refresh-api-types
repos: [api]
done: pushed-branch
artifact: none
machine_bound: false
- name: cut-desktop-installer
repos: [desktop]
done: signed-exe
artifact: installer
machine_bound: true
You are not deciding anything yet. You are making the thing you will decide against.
Done
You know this step worked when every automated job appears exactly once in the list, and each has all four fields filled in - no blanks, no "it depends."
Apply the hand-off test to each job
Mark a job cloud-eligible only if it passes all six rules: it touches one repository; "done" is a pushed branch or pull request; nothing in it is machine-bound; you can push a clean branch before it starts; every key it needs can live outside the machine; and it can run fire-and-forget. One failure keeps it hands-on.
Add the verdict to each job and expect most of your pipeline to fail at least one rule. When I did this across thirty jobs, about five passed cleanly - roughly one in six - and about half could not run in the cloud at all.
- name: refresh-api-types
repos: [api]
done: pushed-branch
artifact: none
machine_bound: false
handoff: eligible # passes all six
- name: cut-desktop-installer
repos: [desktop]
done: signed-exe
artifact: installer
machine_bound: true
handoff: local-only # fails rule 3 (machine-bound) and rule 2 (artifact)
Done
You know this step worked when every job carries an explicit "eligible" or "local-only" verdict and you can name the rule that fails for each local-only one.
Sources
- Claude Code cloud sessions: one repo cloned at your branch, async start, results as a branch or PR, teleportcode.claude.com
- Cloud environments: network access levels, GitHub proxy, network secrets, setup scripts, resource limitscode.claude.com
- Scheduled cloud tasks: an authenticated web trigger that returns a session idcode.claude.com
- CLI reference: starting and steering a session from the terminalcode.claude.com