Run sessions on your own cloud host, started from your laptop

Switch on run in the cloud when you start a session, and it runs on your own host from the checkout you are in, uncommitted work included. It arrives with your agent config, logins and CLIs. Its edits mirror back to your laptop as they happen, and whole batches of sessions move between the two without losing a message.

~/src/shop · feature/checkoutyour laptop
uncommitted
 M src/routes/v1.ts
?? .env.local (ignored)
new session › port the v1 routes
● run in the cloud · start from my checkout
snapshot a41c9e2 + 1 change → refs/codecast/cloud/…
● jx7k2pd running on shop-host
.codecast/worktrees/sync-jx7k2pdin step
  • src/
  • routes/
  • v1.tsM
  • v2/
  • index.ts+12 −3
  • orders.ts+84
  • test/
  • v2.test.ts+40
  • .env.localgitignored
shop-host · linux · awsawake
  • ✓woke the host stopped → running
  • ✓fetched ~/src/shop kept its HEAD
  • ✓copied .env.local setup.copy
  • ✓agent logins pushed claude, codex
  • ✓worktree port-v1-routes made on the host
  • ✓branch feature/checkout reset to a41c9e2, v1.ts uncommitted again
claude · jx7k2pdworktree port-v1-routes
> port the v1 routes
●Readsrc/routes/v1.ts
●Writesrc/routes/v2/orders.ts+84
●Editsrc/routes/v2/index.ts+12 −3
●Bashbun test test/v2.test.ts14 pass

One cloud session, condensed: your laptop on the left, your host on the right, one conversation throughout.

Your hosts sit in Settings, under Devices

Each cloud host has a card in the Machines list there: whether it is awake, what it costs, and whether it carries your setup, logins and tools, with the buttons that fix what is off.

A cloud host's card in Settings, Devices: Awake, t3.medium in us-west-2 at $0.042 an hour, rows for Your setup, Logins, Tools and Host setup, and the Sleep, Apply setup now and Save image buttons
A Linux host, awake. Yellow rows say what is off and how to fix it: here, logins held back because their tokens expired on the laptop, and tools a hook needs that cannot run on Linux.

Wake and Sleep boot the host or stop it costing compute. Apply setup now installs the packages and services your repo declares, and Save image snapshots the machine so the next one starts ready. Your laptop carries each one out, so it needs to be online.

A host also shows up wherever you pick a machine: the machine pill in a new session, the machine menu in a session's header, and Migration in the same settings group.

The Add a cloud machine dialog: Linux or Mac, Connect existing or Create new, the instance, region and SSH key fields, and the setup command it builds with a Copy setup command button
Add a cloud machine, at the foot of the Machines list.

Choose Linux or Mac, then connect an EC2 instance you already run or create a new one. The dialog builds the setup command and Copy setup command puts it on your clipboard. You run it once in a terminal on your laptop, because setup uses your AWS sign-in and SSH key; that one step has no button today.

A cloud session starts from your current checkout

Your branch, your unpushed commits and your uncommitted, untracked and gitignored files all travel. Dependency and build folders are rebuilt on the host. The laptop takes the snapshot with a temporary index, so nothing in your checkout moves.

your laptop · ~/src/shop
a41c9e2not pushedsnapshot commit M src/routes/v1.ts .env.localtemporary index

Your index and branches do not change. The snapshot goes to refs/codecast/cloud/<worktree>, a ref git ls-remote --heads does not list.

the host · ~/src/shop
a41c9e2feature/checkout M src/routes/v1.ts .env.localuncommitted again

The host makes a branch under your branch's name (or <branch>-<hex> if it is taken) and resets it to your HEAD, so the agent sees what you saw.

If the snapshot, push or reset fails, the spawn fails with git's error. It never falls back to origin/main quietly.
  1. 1Wake

    The host boots if it is stopped. Preparation waits up to 3 minutes for Linux, 25 for a Mac.

  2. 2Fetch

    The repo is cloned on the host where it sits on your laptop (~/src/shop there too) if missing, fetched if present. A fetch only: the host checkout keeps its own HEAD and work.

  3. 3Copy secrets

    Files under setup.copy in .codecast/workspace.toml go by rsync, one snapshot per worktree.

  4. 4Worktree

    The host makes its own worktree per task. Dependencies install there and ports are probed on the machine that binds them.

  5. 5Start

    The session row is created pointing at that worktree and routed to the host. Prep runs over SSH from your laptop, which needs to be online; none of it passes through codecast's servers.

In the app, switch on run in the cloud in a new session, beside the folder you picked. start from chooses my checkout (your branch and uncommitted work, as above) or origin/main for a clean start. The session's header shows the host it runs on, and “preparing cloud host” until it is ready.

One worktree per session. Parallel agents on the host never share a working tree. Switch off isolated worktree to run in the host's main checkout instead: that always starts from origin/main on a new codecast/cloud-<hex> branch, and is refused when the checkout is dirty (the files are listed) or another live session holds it (that session is named).

A laptop daemon that is online runs the preparation, wherever you started the session from. With none online, the session waits for one.

for scripts and agents
$ cast spawn --cloud "port the v1 routes" "write the migration"
$ cast spawn --cloud --from origin-main "audit the build"
$ cast spawn --cloud --shared "run the migration"
$ cast fork --cloud "try the queue approach" "try the cron approach"
Agents start cloud work the same way. cast fork --cloud branches a conversation onto the host: each branch gets its own host worktree while your direction stays here.

What the host gets from your laptop, and what it never gets

Before a session starts, the host gets your agent config, shell, logins and CLIs. Each kind travels its own way, and the table says where each one stops.

  • Instructions and agent config.claude, .codex, .gemini, .grok, .opencode, .agents, repo instruction files, git preferences, your codecast switcheshowHome mirror, written atomically with mode 0600. Rescans a minute after each pass; bytes re-verified every 30 minutes.stopsCredentials, transcripts, databases, caches, media, native binaries. Never wakes a sleeping host.
  • Shell.bashrc, .zshrc, fish config, .inputrc, .tmux.conf and every file they sourcehowHome mirror, with laptop paths rewritten to the host's. A login shell there also gets CODECAST_CLOUD=1.stopsExports travel as written, keys included, so keep secrets out of rc files you do not want on the host.
  • Agent loginsClaude, Codex, Grok, Gemini, opencode, pi, provider keyshowOne bundle over SSH stdin. Each file ships only while its token is live.stopsNever through codecast's servers. ANTHROPIC_API_KEY never travels. A bundle for a different user is refused whole.
  • Tool loginsgh, cf and wrangler, Convex, AWS, gcloud, Vercel, Railway, Fly, Netlify, Supabase, Stripe, Expo, kubeconfig, npm, .netrchowLogin bundle over SSH stdin, macOS config paths mapped to Linux ones.stopsAn OAuth login that rotates on refresh ships only while its access token is live.
  • CLIsclaude, codex, gemini, grok, opencode, pi, plus vercel, railway, cf, supabase, stripe, fly, aws, gcloud, kubectl if your shell has themhowInstalled when missing, at your laptop's versions and local to the user, while a session is prepared, at setup, and when you press Wake in Settings, Devices. A wake for queued work only checks them.stopsNo sudo, no system packages: those go in the [host] table. What is missing shows on the host's Tools row.
  • Agent memoryMemories a cloud session wrote or editedhowBoth ways: the laptop brings host memories home before it sends the merged set back.stopsMEMORY.md only gains index lines the laptop does not have yet.
  • Browser loginsOne site's cookies, on requesthowOn the host, cast browser sync <site> asks your online laptop to inject them over an SSH forward.stopsGoogle is never carried. A request no laptop picks up expires in 5 minutes.
The host's card in Settings, Devices shows whether your setup, logins and tools are in step. From a terminal: cast hosts sync --dry-run previews the mirror, cast hosts tools installs missing tools now, and cast config cloud_mirror_enabled false turns the mirror off. A running agent keeps the instructions it read at startup.

Read, run and test the agent's edits on your laptop

A synced cloud session keeps a copy of its folder 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.

session jx7k2pd · sync chipsyncing
Synced with MacBook-Pro
.codecast/worktrees/sync-jx7k2pd · both ways
held: changed on both sides
src/config/routes.ts
stayed on the host
  • node_modules/each machine builds its own
  • fixtures/demo.mp4audio and video
  • data/dump.sql.gzover 100 MB
Cloud to laptop onlyStop syncing

Open the machine menu in a cloud session's header and pick Sync with MacBook-Pro, under “Keep a copy on a laptop, in step”. The agent's edits land in the laptop copy within a few seconds; your edits there reach the agent the same way. A sync chip in the header then shows what is held and what stayed put; Cloud to laptop only sends changes one way. From a terminal, cast remote sync jx7k2pd does the same.

What travels and what stays

Gitignored files travel too. Dependency and build folders, media, compiled programs, files over 100 MB, files a running process owns and nested repos stay put.

Only the conflicting files hold

When both sides change the same lines, just those files pause, each side keeps its version, and you pick one. The rest keeps flowing.

Nothing lands mid-edit

A change applies only if its folder has not changed since it was read. Otherwise the sync retries a moment later.

The host still sleeps

The sync talks to the host only while the session works. An edit you make while it idles goes over once it is awake, and never wakes it.

the agent on the host · jx7k2pd
# the same verbs, carried out by your laptop
$ cast sync status
$ cast sync pull .env.local ~/data/export.csv
$ cast sync pull --ref feature-x
  → laptop/feature-x
$ cast sync diff src/app.ts
$ cast sync push

When something is missing on the host, the agent there asks for it. cast sync pull fetches named files, including ones that stayed home or live outside the repo, and --ref brings a branch only your laptop has.

Tune a repo in .codecast/workspace.toml: [sync] always = ["fixtures/big.bin"] travels where a default would skip it, never = ["data/local.db"] stays on its own machine.

Move sessions between laptop and host in batches

Settings, Migration moves sessions between laptop and host as one batch: pick a destination, tick the sessions, press Move. A session in the middle of a turn finishes it first, and messages sent while it moves are held and delivered on the other side.

Settings, Migration, Destination: two cloud hosts online with their session counts, and three laptops
Settings, Migration: the destination first. Asleep hosts are still offered, and wake on the move.

Pick a destination, then tick sessions in the list below it, filtered by title, project or the machine they are on now. Sessions mid-turn sets how long a busy session may finish its turn, and Move starts the batch.

Every batch then shows under Migrations with live progress, one row per session, each narrating its own step. A failed row keeps its session where it was.

For one session, use the machine menu in its header and pick Move to the host, or right-click sessions in the inbox and choose Move to machine.

  • batch mg-4k7q2z9a
  • jx7k2pdport the v1 routesdone
    resumed on the host
  • jx7m4qewrite the migrationTransfer
    shares a worktree: pushed once
  • jx7c1twfix the flaky auth testQuiesce
    at a prompt: moves now, asks again there
  • jx7p9ranightly backfillWait
    mid turn: finishing first, 2 messages waiting
  • jx7v8hntriage the inboxqueued
    queued: not fenced until its turn
1 Fence

No daemon delivers into it. Messages sent now wait and are delivered when it resumes.

2 Wait

A mid-turn session finishes its turn, up to --wait minutes (10 by default).

3 Quiesce

The owner stops the agent so the transcript on disk is final.

4 Transfer

Worktree by git over SSH, gitignored files, the transcript with paths rewritten.

5 Flip

Owner and path move in one write; the destination resumes, the old owner lets go.

youalso add the v2 rate limits
[codecast] Now running on shop-host (was MacBook-Pro).
claudePicking up the rate limits in src/routes/v2/limits.ts.

Every ownership flip writes that divider into the thread, and the agent is told which machine it is on now. Messages you sent during the move were held by the fence and arrive on the destination.

for scripts and agents
$ cast migrate start --to shop-host --label rollout --dry-run
  would move  jx7k2pd   port the v1 routes  (MacBook-Pro → shop-host)
  skip       jx7q0aa   review the diff: only Claude Code sessions can be transferred
dry run: 1 would move to shop-host, 1 skipped
$ cast migrate start --to shop-host --label rollout --wait 20
The same batches from a terminal: every skip names its reason, and --from, --project, --all and short ids select too. cast remote move and cast remote back move one session; going back is a fast forward that never overwrites local work.

Declare the packages and services a repo needs on the host

A database, a service, a seed script: the [host] table in .codecast/workspace.toml holds it, and every host applies it before any worktree exists.

.codecast/workspace.toml
[setup]
copy = [".env.local"]   # rsynced into each worktree

[host]
packages = ["postgresql", "redis-server"]   # apt
services = ["redis-server", "postgresql"]   # systemd
run = ["sudo -u postgres createuser -s ubuntu || true"]

[sync]
never = ["data/local.db"]
Personal needs go in ~/.codecast/host.toml, same shape. Each run step must be safe to run twice.

It converges on every wake. The spec is applied once per change, before any worktree is made, so a brand new host and an edited spec end up in the same place. A failing step is reported with its output and retried next wake. It never blocks a session.

Save a ready host as an image. Save image on the host's card captures it; the next host you create then starts with packages, tools, checkout and mirrored home already there. The clone gives itself a new machine id and signs in as itself on first boot.

Scripts can tell where they are. Hooks and scripts see $CODECAST_CLOUD set to 1 on a host. Apply it by hand with Apply setup now on the host's card in Settings, Devices, which also shows whether the host is in step.

Browsing and sign-ins on the host

Agents on the host verify UI and read behind sign-ins in the host's own Chrome, borrowing logins from your laptop one site at a time.

browser watch · dashboard.stripe.com/loginTake the wheel
the agent on the host · jx7k2pd
$ cast browser open https://dashboard.stripe.com
# a sign-in wall: borrow the laptop's login
$ cast browser sync dashboard.stripe.com
$ cast browser read

The browser watch beside the conversation streams the agent's tab with its cursor and clicks drawn on top. Press Take the wheel to sign into an OAuth page the agent cannot pass. For a popup, a file picker or a Chrome dialog, the screen button in the watch's toolbar opens the host's whole display in the pane, with mouse, keyboard and clipboard.

The agent drives the host's own Chrome on a virtual display. There is no Chrome of yours there, so when it meets a sign-in it asks your online laptop to carry that one site's cookies in over an SSH forward (cast browser sync <site>, waiting 150 seconds by default). Google logins are never carried.

These views reach the host through the laptop that manages it, over the SSH connection it already holds. An idle listener closes after 10 minutes, so an open tab does not keep a host awake.

When a host sleeps and wakes

A host costs money while it runs, so it looks for real work before it stops and wakes when work is queued for it.

Idle stop

A provisioned Linux host stops itself after 20 idle minutes; its card says “sleeps after N idle min”. cast hosts provision --idle <minutes> changes it; 0 disables.

What counts as busy

Waiting work, open turns, recent subagent activity, live task processes, detached tmux work, CPU. Unreadable evidence keeps it awake. An idle prompt does not.

Quiet jobs

cast hosts keepalive 30 on the host holds it up for 1 to 1440 minutes. A shorter lease never cancels a longer one.

Waking

Work queued for a sleeping host is picked up by your laptop daemon, which boots it. The session resumes from the worktree and transcript on the host's disk. Wake and Sleep on the host's card in Settings, Devices do it by hand.

Macs

AWS Macs run on dedicated hosts: 24 hour minimum allocation, and stopping the instance does not end the charges. Mac auto-stop is off.

Commands for scripts and agents

Everything above also has a command, which is what agents run and what you script. Registering a host is only a command today, built for you by Add a cloud machine. cast <command> --help has the full flags.

Start work on the host
  • cast spawn --cloud "<task>" …One worktree per task, from this checkout
  • --from origin-mainStart clean instead
  • --sharedThe host's main checkout, one task
  • cast fork --cloud "<dir>" …Branches on the host, yours stays here
Mirror and move
  • cast remote sync <session>Keep its folder in step with a laptop copy
  • cast sync status | pull | push | diffFrom the host: what differs, fetch, send
  • cast remote move | back <session>One live session there, or home
  • cast migrate start --to <device> …Many sessions as one batch
  • --dry-run --wait <min>Plan only; how long a turn may finish
  • cast migrate ls | show | cancel | retryBatches, row by row
The hosts
  • cast remote hostsConfigured hosts and this device's id
  • cast hosts lsState, sessions, worktrees, git access, cost
  • cast hosts create linux | macLaunch an EC2 instance and set it up
  • cast hosts add <instance-id> --provisionRegister one you already run
  • cast hosts wake | sleep [id]Boot it, or stop it costing money
  • cast hosts setup | image [id]Apply [host]; save a ready host
  • cast hosts tools [id]Check and install the CLIs and runtimes the host needs
  • cast hosts sync --dry-runWhat the config mirror would send
  • cast hosts vnc [id]The whole screen, in codecast
On the host
  • cast browser sync <site>Borrow one site's login from your laptop
  • cast hosts keepalive <minutes>Stay awake for a quiet job
  • cast ws acquire <name>The worktree a cloud task runs in; the host runs it for you

Requirements and limits

What a host needs, what it costs, and what it cannot do yet.

Where can a host run?

On AWS: Ubuntu 24.04 or macOS EC2 instances, new or ones you already run. Settings, Devices, Add a cloud machine builds the setup command (cast hosts create or cast hosts add), and running it needs AWS credentials and an SSH key on the laptop.

What does it cost?

Whatever AWS charges you; the host is yours. Linux hosts stop themselves when idle and then cost only their disk. A Mac sits on a dedicated host with a 24 hour minimum, billed while stopped.

Which sessions can migrate?

Claude Code sessions with a transcript. Other agents, subagents (they move with their parent), ended or killed sessions are skipped with the reason. Moving straight from one cloud host to another is not supported.

Does my laptop need to be on?

For starting and moving work, yes: preparation and transfers run from a laptop daemon over SSH, and the machine holding a session's files must be online to move it. A running session keeps going with the lid closed. Waking a host for a trigger with every laptop closed needs the backend operator to allowlist it.

Can the host open pull requests?

It pushes with a one-hour GitHub App token scoped to one repo and contents write, so fetch and push work. Calls that need more, like opening a PR, answer 403 unless you log in with gh auth login on the host or grant the device key.

What if a mid-turn session never finishes?

After the wait you chose under Sessions mid-turn in Migration (--wait from the CLI, 10 minutes by default), the turn is interrupted and the row says so. A session stopped at a permission prompt moves at once, and the prompt asks again on the destination. A runner that dies leaves a fence the server lifts after 30 minutes.

Install codecast, then add a host

Codecast runs on your laptop first. When you are ready for a host, open Settings, Devices, Add a cloud machine. It builds the one command that sets the host up, and you run it on your laptop.

1 · on your laptop
Script
curl -fsSL codecast.sh/install | sh
Also via brew install codecast-sh/tap/codecast or npm install -g @codecast-sh/cli
2 · when you want a host, the command Add a cloud machine builds looks like this
$ cast hosts add i-0123456789abcdef0 --provision \
    --region us-west-2 --key ~/.ssh/dev.pem
Taking longer than usualOffline · reloads when back