Blog

Codecast in the cloud

Every cloud feature, end to end: a host in your own AWS account that starts from your uncommitted work, carries your agent config and logins, mirrors its edits back to your laptop, takes whole batches of running sessions mid-flight, and sleeps when nothing is happening.

the codecast team14 min read

Most cloud agent products give you a fresh clone of main in somebody else's sandbox. Your uncommitted change is not there, your .env.local is not there, your agent instructions and your logins are not there, and the agent spends its first ten minutes rebuilding a world you already had. Codecast went the other way. A cloud machine is a computer in your own AWS account that codecast sets up to look like your laptop, and a session you send there starts from the folder you are working in.

This post walks through all of it, in the order you meet it in the app: adding a machine, starting a session there, what the machine is given, how it pushes code, keeping the agent's edits on your laptop as they happen, moving running sessions between machines, watching a cloud session's browser and screen, cloud Macs with iOS simulators, sleep and wake, and the other companies' clouds codecast also shows in your inbox. The limits are at the end, stated plainly.

your laptopMacBook-Prothe checkout you are inyour logins, keychainyour AWS keysyour Chromeyour SSH keysyour cloud machineEC2, your AWS accountone worktree per taskany of your agentsits own Chromeyour config and loginssleeps when idlerun in the cloudyour checkout, uncommitted work includedhome mirroragent config, instructions, memoryloginsone way; the laptop stays the sourcelive syncevery 3 s while the agent worksmove sessionsrunning sessions, messages heldbrowser · folders · screena site's login, a folder, the whole displaycodecastinbox, commands, tokensthe laptop does the workthe machine asks for itfiles and logins ride SSH from the laptop; codecast carries commands and short-lived tokens
Everything that moves between your laptop and a cloud machine. Paper is the laptop, night is the cloud machine.

One idea runs through the whole design: your laptop is the source of truth, and the cloud machine is a second pair of hands. Files and sign-ins go from the laptop to the machine directly. When the machine needs something only the laptop has, such as a site's login, it asks, and the laptop does the work. Codecast's servers carry instructions and short-lived tokens, never your source.

Add a machine

Open Settings → Devices. It lists every machine connected to codecast and whether it is online; under Machines, Add a cloud machine sets up a Linux or Mac machine in your own AWS account. Pick Linux for general development (it sleeps when idle) or Mac for Xcode and iOS work, connect an instance you already run or create a new one, and fill in the AWS details.

The Add a cloud machine dialog: Linux or Mac, connect existing or create new, the instance details, and a Copy setup command button.
Add a cloud machine. AWS bills you directly; codecast never runs machines on its own account.

The dialog builds one setup command, which you copy and run once in a terminal on your laptop, from your project. That step stays on the laptop on purpose: it is where your AWS credentials and SSH key live. Setup installs what a session needs, copies your agent configuration over, and waits for the machine to come online.

From then on the machine has its own panel in Settings → Devices. It shows whether the machine is Awake, Waking, Going to sleep or Asleep, its size and region, what it costs per hour awake and per month for its disk, and when it next sleeps. The buttons wake it, put it to sleep, apply the repository's setup again, or Save image, which snapshots a ready machine so the next one starts ready. Rows for your setup, sign-ins and tools say what is in step, and which sign-ins were held back and why, before an agent finds out the hard way.

Start a session from your screen, not from main

Once a cloud machine exists, the composer grows a run in the cloud switch. Turn it on and the new session runs on the machine in a worktree of its own. Two more choices sit beside it. start from is my checkout (your exact working state) or origin/main (a clean start). isolated worktree, on by default, can be turned off to run in the machine's main checkout, for a job like a data migration that must run where everything else is; that is refused if the checkout has changes or another session is using it. An asleep machine wakes when the session starts, and the header reads preparing cloud host while its checkout is made.

The new-session composer's switches: isolated worktree on, run in the cloud on, start from my checkout or origin/main.
The composer with run in the cloud on, starting from your checkout.

“My checkout” is the part that took the longest to get right. Your laptop takes one snapshot of your folder, ignored files included, without moving anything in your checkout. The machine restores it so your uncommitted edits show up as uncommitted again, and checks that its folder matches yours before the agent starts. Any agent works there: Claude Code, Codex, Cursor, Gemini, opencode, pi or Grok.

Two commit graphs. Laptop: an unpushed commit and modified files captured into a snapshot. Cloud machine: the same commit with the files uncommitted again.
The snapshot carries your exact working state, and the machine restores it as uncommitted work.

Not everything should travel. Dependency folders are rebuilt on the machine, because a node_modules built on a Mac is wrong on Linux anyway, and big untracked media and binaries stay home. Each file left behind is listed under the reason it stayed, so you can see the decision rather than discover it.

Travels
Captured through a temporary git index, so nothing in your checkout moves.
  • →your branch and unpushed commits
  • →uncommitted edits, staged or not
  • →untracked files
  • →gitignored files: .env.local and friends
  • →tracked files of any size
Stays, with a reason
Each skipped file is listed under the reason it stayed, so nothing vanishes quietly.
  • node_modules, .venv, dist, target, Pods…rebuilt
  • an untracked video or audio filemedia
  • an untracked native binary ≥ 256 KBbinary
  • an untracked file over 100 MBlarge
  • untracked files past 1 GB, largest firsttotal
  • sockets, pid files, database journalslive
  • a repository nested inside this onerepo
What a cloud start carries. Tracked files always travel, whatever their size; .env files travel too, since both machines are yours.

Agents can start cloud sessions too. One that fans out five tasks gets five worktrees from a single snapshot, so all five start from the same instant of your work (for an agent, that is cast spawn --cloud).

The machine is set up like your laptop

An agent is only as good as its context, and most of the context lives outside the repository: your agent settings, your CLAUDE.md, the skills and hooks you wrote, the shell setup your hooks assume, the sign-ins for the tools your agents call. You never set a cloud machine up by hand. Before a session starts, and whenever the machine wakes for one, your laptop brings it into step:

ip-172-31-40-243 · before the agent starts
  1. ✓diskrefuses to start with under 1 GiB free
  2. ✓castbrought to the laptop's version
  3. ✓[host] setuppackages, services, run commands; skipped when in step
  4. ✓loginsClaude only while its token is live; never refreshed on the host
  5. ✓toolsagent CLIs, node, bun, gh, uv at your versions, no sudo
  6. ✓gita credential helper that asks for one token per push
  7. ✓home mirror~/.claude, ~/.codex, CLAUDE.md, shell rc, memory
stays on the laptop:ANTHROPIC_API_KEY~/.sshkeychainsGoogle loginsbrowser profiles
The machine's checklist before a session starts. Every step except the disk check and the configuration copy may fail without blocking work, and says so in the machine's panel.

Your agent setup travels: agent settings, instruction files, skills, hooks, your shell setup and your agents' memory, with laptop paths rewritten to the machine's. Memory comes back the other way too, so what a cloud session learns is not stranded there. Credentials, transcripts, caches, SSH keys and browser profiles never travel.

Sign-ins go one way, from your laptop to the machine. The Claude sign-in is the delicate one: refreshing it on the machine would log you out at home, so the machine is never allowed to refresh it, and your laptop sends a fresh one when its own renews. Your Anthropic API key deliberately stays home, because its presence would move every Claude on the machine off your subscription and onto metered API billing. Tools arrive at your laptop's versions, installed for your user without admin rights.

When a repository needs more on the machine, a database or a system package, ask an agent to add it to the repository's codecast setup. Every machine applies it before the next session starts, and skips it when it is already in step.

Pushing code without leaving a key on the machine

A machine that runs agents unattended should not hold a long-lived GitHub token. With the codecast GitHub app installed for a repository, the machine asks for a token each time it pushes, and codecast hands back one scoped to that one repository, after checking that you are allowed to push. It expires within the hour and is never written to disk.

on the hostoff the hostgit on the hostcredential helpercodecastGitHub Appcredentials for github.com?a token for this repomay this person push?installation token, 1 repoexpires within the hourhanded over, never on disk
One push from a cloud machine. The token lives about as long as the push does.

Where the app cannot help, Settings → Devices marks the repository needs access and shows the machine's own public key with a Copy button. Add it on GitHub as a deploy key with write access, and pushing starts working within minutes.

The agent's edits, on your laptop, as they happen

A cloud session is only half useful if its work is stuck there. Click the machine name in a cloud session's header and choose Sync with your laptop. The session's folder is then kept in step with a copy on your laptop, both ways, a few seconds behind. Open it in your editor, run the tests locally, or fix a line yourself and let the agent see it. A chip in the header shows the state: syncing, in step with the time of the last sync, or sync paused while the session is idle, so the machine can still sleep. Its menu opens the copy in Cursor or VS Code.

When only one side changed, its changes land on the other. When both changed, the files that merge cleanly land, and a file changed on both sides is held as it is on each side while everything else keeps flowing. Only files that actually changed are written, so your editor and your dev server do not see a storm of rewrites.

hostlaptop3s6s9s12s15s18s21s24sv1.tsv1.test.tsv1.tsREADME.mdroutes.ts held: changed on both sidesv2.ts still landed on the laptopagent goes quietpaused: laptop read every 15 s● host edit ● laptop edit ● same file on both sides ┆ sync tick
Thirty seconds of a synced session. Ticks run every 3 s while the agent works, and pause when it goes quiet.

A held file never gets conflict markers written into it: the chip lists it with Keep the laptop's and Keep the cloud's. Cloud to laptop only turns the copy into a mirror you read rather than edit, and if you edit it anyway, the sync stops and asks whether to send your edits or take the cloud's.

The machine menu for a synced cloud session: synced both ways, one file held because it changed on both sides, and a list of what stayed on the cloud machine.
A conflict holds one file, not the sync. Heavy and machine-specific files stay on their own side, listed with the reason.

Move running sessions before you close the lid

The most common reason to want a cloud machine is the moment you need your laptop back: a flight, a meeting, a laptop pinned at full load. Click the machine name in a conversation's header for Run on device · which machine, and pick where the session should run. An asleep cloud machine is marked asleep, wakes on move.

The machine menu in a conversation's header: the session is running here on the MacBook Pro and can move to Cloud Linux or the Mac-mini.
The session runs here on the laptop; it can move to either cloud machine.

For many sessions at once, select them in the inbox and choose Move to…, or open Settings → Migration. Migration lists your sessions with filters, and you pick a destination: each card says whether the machine is online and how many sessions already run there.

Settings, Migration, Destination: cards for Cloud Linux and Mac-mini (cloud hosts, online) and a MacBook Pro (laptop, offline), each with its session count.
Settings → Migration: pick where the selected sessions go.

Then you decide how to treat a session that is in the middle of a turn. It finishes the turn first, up to the wait you choose, or is interrupted at once. Anything you send it meanwhile is held and delivered on the other side. A session waiting on a permission prompt moves at once and asks again on the new machine.

How to handle running turns: Sessions mid-turn set to Wait up to 10 minutes, and Transfers at once set to 2.
Mid-turn sessions get to finish. Messages sent meanwhile wait and arrive after the move.

Each session walks through the same steps, shown live under Migrations on the same page: new turns are held, the turn finishes, the agent stops, its work and conversation transfer, and it resumes on the other side. Coming home, the cloud machine's work lands in your checkout as uncommitted changes. If it does not apply cleanly, that session fails with the reason, nothing in your folder changes, and the session keeps running where it was.

queuedwaiting for turnstoppingtransferringhanding offresumingdonejx7k2pdidle at a promptjx79tnwmid-turn, finishes first2 messages heldjx72ss5at a permission promptasks again on the hostjx77bkwhost checkout busyfailed · restarted where it wasjx75me8queued behind twosessions transfer two at a time by default; a turn gets 10 minutes to finish before it is interrupted
A batch of five, schematic. A failed session restarts where it was; nothing is left half moved.

The conversation marks the move with a rule reading now running on …, and the agent is told, so it does not go looking for a dev server it left behind:

[codecast] This session just moved to a different machine. It now runs on
Linux - ip-172-31-40-243 in /home/ubuntu/work/codecast (previously
macOS - MacBook-Pro-182). Processes, ports, and any files outside the working
tree from the previous machine are not here.
What the agent reads after a move.

Run here, on any laptop, brings a cloud session home without interrupting a turn in progress. And when your laptop is under sustained pressure (memory, CPU, or load for a minute or more), the Resources page offers to offload sessions to a cloud machine, spreads them for you, and waits for you to confirm. On the iPhone app, tap the machine in a session's header to move it.

A Codex session running on a cloud machine, with its browser tab, in the same inbox as the laptop's sessions.
A cloud session sits in the same inbox as everything on your laptop, browser tab and all.

Watch the cloud machine work

A cloud machine has its own Chrome, so agents there verify UI and read behind sign-ins without touching yours. watch live on a browser step shows the agent's tab beside the conversation. Take the wheel gives you the mouse and keyboard, for example to sign in where the agent cannot, and Hand back returns it. When an agent needs a site you are already signed in to, your laptop copies that one site's login across. Google logins are never copied.

For anything outside the tab, a popup, a file picker or a native dialog, the screen button opens the machine's whole display in a Host screen pane. The tmux pill in the header opens the agent's terminal; typing works there, a moment behind. Agents on the machine can also drive native Linux apps the same way they do on a Mac.

One capability is command-line only today: mounting a folder from your laptop on the cloud machine at the same path, with no copy (cast hosts reach ~/notes). The laptop serves just that folder from a locked-down sandbox, and the folder is there only while your laptop is.

Cloud Macs and iOS simulators

A cloud Mac is for work that needs Xcode. Add iOS simulators to the repository's codecast setup (or ask an agent to), and the Mac gets a copy of your laptop's Xcode, the iOS runtime and the tools agents use to drive a simulator. From then on an agent on the Mac installs its build in a simulator, taps through it and puts screenshots in the conversation, exactly as it would on your laptop. The first Xcode copy is slow, close to an hour for us; it happens once.

It sleeps when nothing is happening

A machine that runs all night for nothing is the fastest way to stop trusting the feature, so a Linux machine watches for real work and stops itself without it. Real work means an agent mid-turn, a background job, someone watching its screen, or a process using CPU. An agent idling at a prompt is not work. After twenty idle minutes the machine powers off, and a stopped machine costs only its disk. Its panel in Settings → Devices says when it will sleep.

0 min10 min20 min30 min40 min48 minagentturn ends; an idle prompt is not workwatchdogchecks 5 min after boot, then every 2idle for20 idle minutesstoppeddisk onlypoweroffa trigger fires for ita laptop sees the request,starts the instance;answered 60 s later
Schematic, except the wake: on September 5 a queued trigger reached a stopped machine's session 60 seconds later.

Waking is automatic. Work for an asleep machine, a message, a moved session or a scheduled trigger, wakes it through your laptop, and the work starts once it is up. You can also press Wake in its panel. A Mac is different: its AWS host bills while allocated, awake or asleep, so it does not sleep on its own.

When something breaks

Machines fail in boring ways, and most of the work here went into making the failures boring too. If an agent's process dies in the middle of work, on a cloud machine or a laptop, codecast restarts the session with a note explaining what happened, at most three times in six hours, and never one you stopped yourself. A move that stops reporting for thirty minutes is failed, and the session stays where it was. The machine's panel shows which sign-ins and tools are missing before an agent trips over them.

The other clouds

Your cloud machine is not the only cloud your agents run in. Codecast also shows, and mostly drives, the cloud agents other companies run, in the same inbox and the same search as everything else. Add a Cursor key and your Cursor Cloud agents appear as sessions; the composer's run in Cursor Cloud starts one, and your messages become its follow-ups. Turn on Codex Cloud tasks and run in OpenAI's cloud starts one with up to four attempts, then Create draft PR or Apply locally. Claude Code sessions you started on the web show up with their full transcripts, and you can reply from codecast.

Whose machineStarts fromLaunch from codecastFollow-upsMoves to your laptop
Your cloud hostYours, in your AWS accountYour checkout as it is, or origin/mainYes, any agentYesClaude Code sessions, both ways
Cursor CloudCursor'sThe branch as it is on GitHubYesYesNo
Codex CloudOpenAI'sThe repository on GitHubYes, 1 to 4 attemptsDraft PR, apply locallyNo
Claude Code on the webAnthropic'sA session you started on claude.aiNo, mirrored onlyYesNo
Four kinds of cloud session, one inbox. Only your own machine starts from your uncommitted work.

The difference is the starting point. A vendor's cloud starts from what is on GitHub. Your machine starts from what is on your screen, which is why we built it.

What it needs, and where it stops

  • Waking a sleeping machine needs your laptop online. Work sent to an asleep machine wakes it through the laptop that manages it. If that laptop is closed, the work waits.
  • Only Linux machines sleep on their own. A cloud Mac stays up, and AWS bills its dedicated host for at least 24 hours either way.
  • Only Claude Code sessions move. Any agent can start on a cloud machine, but moving a running session between machines works for Claude Code, and never straight from one cloud machine to another.
  • Most tool sign-ins travel when they exist. Claude, Codex, Gemini and a few others travel only while their sign-in is valid. Sign-ins for tools like GitHub, AWS and npm travel whenever your laptop has them. Your Anthropic API key and your Google logins never do.
  • Adding a machine runs one command on your laptop. The Add a cloud machine dialog builds it for you, because your AWS credentials and SSH key live on your laptop, not in a browser.
  • A cloud Mac only applies part of a repository's setup. System packages and services are set up on Linux machines; on a Mac, setup commands and iOS simulators apply.
Codecast is where your team sees, steers, and remembers every coding agent session, on any agent and any machine, including the ones you rent.

The screenshots of Add a cloud machine, the machine menu and Settings → Migration are single elements of the real app, captured from the codecast team's own workspace on 2026-10-09 with nothing else in frame; two unrelated offline machines are hidden from the menu and the destination list. The 60 second wake was measured on 2026-09-05. The figures are drawn from the code's own constants (tick rates, timeouts, idle minutes); the migration batch and the sync timeline are schematic. Three illustrations come from the field manual's cloud chapter. If you script codecast, every action here also has a cast command; cast --help lists them.

Taking longer than usualOffline · reloads when back