When a cloud session won't start
A cloud session uploads your project to a fresh machine before the agent can start. The app works out how big that upload is before it rents anything, sends one project upload at a time, says what the upload is doing while it waits, and tells you plainly why it stopped when it does. If a session cannot start, the message names the real reason and the way out instead of leaving you to guess.
On this page
What it is
Before an agent can run on a cloud machine, your project has to get there. That upload is the slow part of starting a session. The app measures your project before it rents anything, sends one upload at a time, and when it does stop, says why.
Where to find it
Nothing to open and nothing to switch on: this is not a screen you visit, it is what you see while a cloud session is starting. When one cannot begin, the reason appears in that session's own transcript, in place of the old vague "couldn't finish starting up", naming the size, the file count and the way out.
To see how far a launch got and what it sent, read Reading a cloud session's state — the same facts the transcript's reason is taken from.
How it behaves
What you will notice
- Starting several cloud sessions at once is safe. They take turns uploading instead of competing. A session that waits does so before its own upload begins, so waiting costs it none of its upload time.
- A launch that never takes a turn ends by itself. The app tells the cloud controller and settles the launch on a bounded timer: the session ends as failed instead of sitting in "starting" and raising the same alert every few minutes. Nothing is deleted and you can retry it.
- A session that cannot start says so, and rents nothing. A project too large to upload within the time a session may spend on it stops before any machine is created, naming the size, the file count and the way out.
- A session that hands its work back through GitHub refuses to start without a repository. Such a
session sends its work home as a commit, so its project has to name a GitHub repository. That is
checked before anything is rented or joined: a project with no
originremote, or an origin that is not a GitHubowner/repo, is refused at once with that reason and the fix, instead of renting a machine and dying minutes later with a message about the SSH connection. The app cannot read which repository the cloud controller is set up for, so a project whose origin is a different GitHub repository is still refused by the controller, after the machine has been rented. - A session refuses to start in a folder that is no longer its own. A shared machine holds one copy of the project per session; if a copy loses its own git repository, an agent's work would land in the machine's shared repository and could never come back. The copy is checked first: the session does not start, the message says so, and the machine is kept with its disk intact. The copy that creates a folder makes it its own repository before writing anything into it, so an interruption cannot leave that state behind; a folder already in it is left as it is and reported, never deleted, because it may hold work that has not come home.
- A session shares a machine only when that machine holds the same packages. Otherwise it gets a machine of its own rather than rebuilding packages there — a rebuild never fits the time a join is given. A machine is never taken out of service over this; a later launch with matching dependencies joins it normally.
- A non-git project sends only what its ignore file allows. It used to go up whole, unmeasured.
The app lists the folder with git's own ignore rules (changing nothing), measures before renting,
and refuses up front with the size named. Secret
.envfiles never travel, and a nested git repository is left out and named. Such a folder cannot use a saved copy, so every launch sends its whole list; making it a git project lets later launches send only changes, and lets the work come back. - A session that waited too long says so and cleans up. If the sessions ahead take longer than the longest wait the app will hold, a session that never gets its turn stops, removes the machine it had started, and says how long it waited.
- A session tells you what its upload is doing — when it starts waiting and how many are ahead, when its turn comes and how long it waited, and if it gives up on sending only the changes and sends the whole project. Nothing has failed, and none of those is a stopping point.
- A failed start no longer leaves a machine behind. A machine whose start failed before any agent ran on it is removed outright.
- A machine the provider turns down for a moment retries by itself, and what it said is recorded. The refusal arrives as a plan-or-billing message though the account is fine, in bursts when several sessions start at once. The app reads your account's remaining starts: when they show the refusal is not real it waits, retries on a backing-off schedule for up to an hour, and tells you if it still has not managed. Every refused attempt records the provider's own code and body. If the account really is out of starts, the message names the limit and the session stops.
- A machine that will not stop is reported, not retried forever. Parking is how the app stops paying, and a machine counts as stopped only once read back as stopped. After three failed attempts the app stops trying and raises one inbox notice naming it, so a machine still costing money is something you are told about.
- A machine with nothing running stops itself. Close your laptop, quit the app or walk away, and it shuts down once nothing has worked on it for about half an hour, without waiting for the app to return. It is held open while its agent is mid-turn, while a turn has stopped to ask you something (half an hour after), and while any session sharing it is still working; with "keep machines running on quit" set, a working turn holds it for up to two hours instead. Stopping this way saves the disk, so the session comes back where it left off. While the app runs it shuts an idle machine down through its normal shutdown, which brings the work home first and records that it can later be cleared — after a restart too.
- A launch's status notes fold into one line. The chat shows "Cloud machine setup · 4 notes"; click it for what the machine started, what was sent, anything of your own setup left out, and what the cloud cannot have. A failed start always shows on its own line, and "your cloud changes are back on this computer" gets its own card (see returned cloud work).
- A launch that could not set up your latest commit says so — on the git road, "couldn't finish starting up (your project's latest commit could not be set up on the cloud machine…)". Nothing on your computer is changed, and sending the session a message tries the cloud again.
- A launch the cloud credential gateway turned down says so. The session names which pass failed: "Cloud managed model gateway pass is unavailable" (a managed row), "Cloud account gateway pass is unavailable. Retry when the gateway is reachable" (your own account), or "Could not provision this cloud account credential" (the sign-in could not be read, or the credential could not be handed over). A hand-over the gateway refuses is different: that launch is stopped, and "The cloud gateway refused this session" names the refusal — a 401 names the refused key or sign-in instead. Nothing on your computer is wrong.
- A launch whose key or sign-in is refused says so, instead of blaming the connection. On a 401, an invalid or revoked key, or an expired token, it reads "The Claude key or sign-in was refused, so this session could not start. Replace the key, or sign in again, then start the session again — retrying without changing it gets the same answer." The vendor named is the one that refused (a DeepSeek session says DeepSeek; "The AI provider’s key or sign-in" when the app cannot tell), and the provider's own answer is written to the log, never shown.
- A Claude account with no sign-in is told to sign in, on either road — "This cloud session has no Anthropic credentials to forward — sign in, then try again", with a link to the sign-in setting. Signing back in is the whole fix.
- A pass the gateway would not give gets one inbox card. When the gateway will not hand a session its temporary pass but this computer can carry the session instead, the session still starts and one card — "A cloud session couldn't get its pass from the cloud gateway" — says it did not reach its model directly. Sessions allowed that backup use this computer's upload bandwidth; DeepSeek cloud sessions never do, so they cannot start until a pass is issued. It clears once passes are issued again: for each kind of session (your own key, Omniscio credits or company funds, your Claude account) the first launch that gets a pass at least ten minutes after that kind last failed ends that kind's problem, and after a restart the first pass takes the card down while the next refusal raises it again.
- A DeepSeek launch that may not use this computer's model relay says so — "DeepSeek cloud model traffic requires the cloud gateway… No desktop model relay will be used" — and the group card repeats it. The launch works again once the gateway is reachable.
- The "a session never started" card names the session it is about, each dead session in its own row carrying its id, so four failed launches are four rows you can tell apart.
- A launch that dies because your AI provider's account is out of money says so. When the funding account has nothing left — DeepSeek's "Insufficient Balance", or the app's gateway relaying that rejection — the session names it: "The DeepSeek account is out of money, so this session could not start." Add credit and start again; switching models will not help while the account is unfunded. A session that hits this while running keeps its own copy naming the same account — or your Omniscio credits, when it ran on those — and only that copy is guaranteed: the group card repeats the reason when the provider's balance can be checked (DeepSeek and Kimi), and otherwise says it could not show one.
- Cloud launches failing as a group get one inbox card. Five launches in a row failing within half an hour raises "Cloud sessions are failing to start", saying how many failed, what failed, how many each cause accounted for, and when a cloud session last started successfully (left out if none since the app opened). It gets a newer count while failures keep coming and stays up for the whole outage, then goes once a launch succeeds; if launches simply stop, it comes down at the next attempt after half an hour with none tried (unless that attempt fails too) — nothing removes it on a timer. It never fires for launches refused on purpose.
- A card about launches cut off by a restart comes down by itself. It offers Resume them now, and clears as soon as the session it names has been resumed (from the card or on its own), archived or deleted; a card naming several sessions is narrowed to the ones still waiting. A session still stuck keeps its card.
- After "Continue in the cloud", the original waits while its cloud copy works — not on a scheduled check-in, a restart or the app's own recovery — so the same work never runs twice. Archive the cloud copy (or delete it) and the original works normally again; a "send later" message waits and goes out then. Above its reply box it says "This session moved to the cloud" with an Open cloud session button, and a reply that cannot go through offers the same click.
- A message to the original goes to its cloud copy — from its chat box, one of its inbox cards,
or a queued message — and the original's chat shows a line naming where they went. The original
also leaves your Needs You list. If the cloud copy is mid-step your message waits. Messages other
agents send go the same way, and a Restart on the original says which session the work was handed
to (
"<session name>" was handed over to a cloud session…) so the warning is clear even if you have moved on. - A crew session keeps its place in the crew: if the session you continue in the cloud is a lead, foreman or helper, its place moves to the cloud copy — tasks, check-in rhythm and (for a foreman) helpers. If the move fails, the crew's board says so.
- A retry re-sends your first message's attachments too — the screenshots and PDFs, even when that message was only a screenshot. A message you send to try the cloud again carries its own attachments; other file types (.docx, .txt) are not re-sent.
- A provider with no machines right now makes the session wait, not fail. The session parks without being marked finished and the app retries (after 1, 2, 5, 10 and 15 minutes, inside an hour) while its note says it is still trying. That count survives a restart; if the hour is gone it tells you it has stopped. At the end one inbox card offers Restart it — that button, and a message you send, both start a fresh attempt. A crew lead reviving it meanwhile is told the provider has no machine and the app is retrying, not that an account is at its limit.
- Archiving a cloud session gives its machine back straight away. A machine that keeps its disk while stopped counts against the provider's limit, so an archive used to hold it for up to a day; once a session's work is proven home, its machine is deleted and its slot comes back. If anything cannot be proven safe — another agent still working on it, a session it hosted not archived, work not home, a branch not landed — the machine is kept and one card names it, as it is for a machine the app cannot ask (stopped before this shipped) until it is next started and stopped again.
- Nothing changed for ordinary projects — everyday launches, including large ones, start exactly as they did before, and nothing new is asked of you.
What it costs
Nothing new. The check and the queueing cost no extra money and no setting; the change only prevents spending on uploads that could not finish.
If you see the message about a project being too large to upload
That message is the app declining to spend, not a fault in your project or your connection. The way out it names is the real one: if the project has its own code repository, connect it, and later launches fetch its files from there instead of uploading them — faster, and free of the upload time budget.
If a launch stops because it could not use the project's repository
Once this computer can read a project's own repository, a launch fetches the files from it instead of uploading them. If that fetch starts and fails the launch stops, rather than fall back to the whole upload. Two faults are named separately because only one is yours: a failed fetch means the repository key is wrong or missing, or the host unreachable; a failed checkout means the files WERE read and the app could not place them — a fault in the app, so retrying may not help and it needs reporting. A repository the app cannot use at all is different: with no key here, or a branch the repository does not hold, the launch keeps every other road and uploads the whole project; a remote is never on its own a reason to stop.
If a session says its commits could not be sent over the git road
A cloud session's code normally reaches its machine as a commit: the app measures a small delta from the commit the machine already holds and pushes only that. When the measurement itself cannot be made, the launch is refused rather than started on a tree nobody asked for, so this message is about the app's own copy of the project — not about anything you did.
This computer keeps a deliberately thin copy of the repository (commits and folder listings, not the older contents of every file). Until 2026-11-12 a launch measured its range without first fetching the file versions that range needed, so a stretch of history this computer had never checked out made the measurement fail and killed the start — most often just after the app itself restarted. The range is now fetched first, and the launch record keeps the road's own reason for any refusal that does happen, so "send a message to try again" is the whole remedy for the old shape and a repeat now names its cause.
If a session sits on "starting" for a long time
A launch may first try to reuse a shared cloud machine this computer already has. Bringing that machine to your project's latest commit means sending it everything it is missing, and when the machine is far behind that send is tens of megabytes — minutes of transfer over the same uplink. Since 2026-11-14 the app measures that transfer before it starts one: if the pack cannot arrive inside four minutes, it leaves that machine alone and rents a fresh one, which starts in about six minutes instead of waiting out a send that would not finish. A launch still saying "starting" after about ten minutes is worth a look; before this, twenty to thirty minutes was normal, and stopping it in that window threw away a launch that was still working.
If a launch is refused because the day's machine starts are nearly used up
The app keeps the last of the day's starts back, so a running session can always be brought home. A refusal applies to the machine account it would have charged, so a launch sent to a different provider is not refused, nor one that takes a machine this computer already has awake. It clears itself, and a launch that named no provider behaves as it always did.
If a relaunch says the machine is busy on this computer
After a restart, a session whose cloud machine was parked may need waking again. When another of this computer's own tasks still uses that machine, the message says exactly that instead of blaming the provider. A copy of the app that is no longer running stops counting as a user. Wait a moment and try again.
If your reply to a cloud session seems to vanish (2026-11-06)
Many sessions can share one cloud machine, and a few jobs need it to themselves — stopping it, removing it, wiping its secret files. Such a job now holds the door for at most a minute at a time, then steps aside so waiting sessions get in, and tries again; it never runs while anyone is using the machine. If a reply cannot get through, the session says so in the conversation — "Your message didn't reach the agent", the reason, and to send it again — instead of staying silent.
If a launch that a restart interrupted cannot pick up where it left off
A launch cut off by a restart is picked up on the machine that already holds it. The session's copy there is moved to your project's latest saved commit, so the launch starts from your current work instead of the older commit it was given before the restart. When that machine holds commits of the agent's own that never came home, the launch carries on from them: they are brought home first and the session picks up where the agent left off. One case still stops by name — a branch the app cannot prove is this session's own, one that does not descend from its last launch — and that stop leaves every commit where it is. A failure here carries the machine's own words about why, so a bare "exit code 1" never stands alone.
If the app closed before a cloud session could start
A cloud session takes a few minutes to get going, and the app can close in the middle. A launch the app's own shutdown cut off is set aside as interrupted and starts again by itself the next time the app runs — same cloud machine, same task. With automatic resume off, send it a message and it starts the same way. If that machine cannot be reached, the session stops with a message saying so and you can start it by hand. When Agent 37 answers clearly that the machine is broken, the app removes it and starts the session on a fresh one — never while it still holds work that has not come home, or while another session is using it. An account problem (an expired key, an unpaid bill, a plan limit) still stops the session and keeps the machine. Only a launch the app refused because it was closing is treated this way; one that genuinely failed still stops and tells you why.
If a cloud session keeps failing to start (2026-11-18)
A session whose start keeps failing — the model gateway refusing it, or the machine not answering yet — is retried a few times, at one, two and five minutes. One part of the app owns those retries now, so a second one can no longer re-wake the same session in between and keep the count from ever running out. When the last try fails, the session stops trying and moves to Needs you with a message naming what kept it from starting; nothing is lost, and starting it again by hand, or fixing the cause it names (a DeepSeek balance or key, say), brings it straight back.
If a cloud session says its setup bundle is missing
Every launch puts a small setup bundle on the machine before the session starts. It is built on your computer rather than stored with the project, so cleaning up your working folder can remove it, and the launch rebuilds it from the app's own source the moment it is missing, well under a second. If it genuinely cannot be rebuilt — a packaged install with damaged files, or a folder the app cannot write to — the message says the bundle is missing and could not be rebuilt, and asks you to send the diagnostic bundle.
If you press Retry and a cloud session never gets its machine
Retry starts the cloud session again on a fresh machine, through the same road Restart uses, so the session comes back with the task it was created with. You get the usual lines ("Setting up your cloud session…", then the machine starting), and a refusal is explained in the conversation. It will not quietly retry a setup refused for a reason no retry can change — a project too large, a repository it cannot read: your one press is the one attempt, and a second refusal shows the same reason. It never starts a second machine for a session that still has one.
If a session's cloud machine is gone, or has stopped answering
A session parked mid-task (waiting at a pipeline gate, say) is resumed when you — or its crew lead — send it a message. If its machine is in trouble the app says which state it is in:
- The machine is gone. The provider no longer has it (a 404). The session parks as machine gone, the note names the machine, the work is kept on a saved branch, and one inbox card records that the machine went away holding work never proven home. Send a message and a new machine starts from that branch.
- The machine is not answering. The provider still reports on it, but its agent never answers — every command times out. Before parking as machine unreachable, the app restarts that agent over SSH and probes again (the repair a crash-recovery wake runs). When it answers, the message you sent relaunches the session in the same go; ONE message brings it back. If it still does not, the note says what is true: the disk and the work are held for three days, nothing is lost, and the work can be brought home so the session starts on a fresh machine. The note never tells you to send a message — that is the action that just failed.
- The refusal came from the cloud controller, not the machine. The controller would not hand the session back (another run still holds it), so the note is the controller's own sentence, saying it comes back when that run ends. It is about the session, not your connection, your machine or Claude Code; the same sentence appears when the controller will not let a new copy of the agent start because the previous one has not let go. A "controller was busy" note is retried by the app a few times over the next seconds, and a message you send starts a fresh attempt. If it keeps coming back and the session never returns once its run has ended, report it.
Neither park is a give-up: both clear on the next message. Only a failure genuinely the session's own — a project that is gone, a folder that is not a repository — still ends in the ordinary "recovery failed" park.
Restarting one of these now starts its machine. A restart wakes the machine without asking the controller first — the road the app uses to bring work home — and the session comes back. A session waiting on something other than a machine — a question, an approval, a parked budget — keeps the restart it had.
When a FINISHED session's machine is gone with work still on it, one card — "Work stranded on cloud machines the provider no longer has" — names each machine and its sessions. Often that work already reached the main branch another way, and then nothing needs rebuilding. If a cloud session's unfinished work could not be written off, send the diagnostic bundle to support.
If a cloud session says the route home to the app is DOWN
A cloud session talks to this app through a small relay on its machine. When the app is busy for a few seconds its answers come back late; the relay now waits as long as the machine's own health check, up to about twelve seconds. It still reports DOWN quickly when the route is truly gone, and a stall that ends no longer makes the machine restart a working relay. If a session still reports DOWN, the app was silent longer than that: send it a message once the app is responsive and it carries on.
A LONG WRITE IS NOT A DOWN ROUTE. A ready mint (or a land, or a publish) can take minutes, and while the app is working on that request it answers no health probe either — so the relay waits for the answer it already asked for instead of calling the route down or the request "may have been done". Reports and questions still fail fast: those can safely be asked again.
If a cloud session says a request MAY have been delivered
That is the relay saying the request reached the app but no answer came back in time — the work may
already be done, so nothing about the app is down. The way back is the same request re-run with the
same X-Client-Request-Id, which replays the original result instead of doing the work a second
time; a sender that has no such id reads its own sent list before sending anything new. A fresh copy
under a new id is what delivers the same message twice, so it is never the answer. You never have to
guess: even a route that closes its end without answering still returns this message, rather than
hanging up with nothing.
If a session you moved to the cloud says it is "already being continued"
A session you continued in the cloud is its own copy of the work, and that copy restarts on a fresh machine when you message it. A genuinely second cloud copy is still refused, so one piece of work never rents two machines.
If the machine provider's account has run out of money
A provider with no balance cannot start a machine, and retrying changes nothing — so this is the one money-shaped refusal that moves a launch on. The app continues on the next provider on its fallback list (Agent 37 if set up here, otherwise the Google backup), and one inbox card says which provider is out of funds. Nothing was created or charged for the refused attempt, and once funded, launches start there again. A declined card, a lapsed plan and a used-up daily start limit are NOT this case.
If Agent 37 cannot be reached at all
When the app cannot even connect to Agent 37 — the connection is refused, its address cannot be looked up, or the attempt times out before anything was sent — the launch continues on Boat, and there is no Agent 37 machine to pay for. If the request DID reach it and only the answer was lost (the 120-second wait ran out), the launch still stops: Agent 37 may already be building that machine, and a Boat one too would leave two billing. A team session, a project set not to switch providers, and the backup switch turned off still keep a launch on Agent 37. If Boat cannot start a machine right now, the launch stops with Boat's reason and nothing was rented.
If this computer has spent its backup-machine budget
Backup machines are the ones paid for whenever the main provider has an outage. This computer keeps a running total in machine-hours, from the provider's own record of when each machine was created and how long it may run; everything here is off by default except the notice.
What you will notice. If the backup holds more than the budget, one card names the hours and the sessions using them. Nothing is stopped and every launch behaves as before. Each machine counts as the time since it was created, so one left running for days is what pushes the total up — that is the leak.
The part that is switched off. A second switch makes the app refuse the next backup machine instead of renting it: that session parks with a note naming the hours, the budget and the sessions holding them, and the way out — stop those sessions, or raise the budget, and start again. Nothing is charged for the refused attempt. It is off by default because refusing a backup machine fails a launch you asked for. The budget is a number, not a policy: the app ships one so a number exists, and it is yours to change.
If a cloud session is told to continue after it already answered (2026-11-07)
A cloud session that stops partway through its work is nudged with a short "Please continue", because nobody is watching the machine. The app used to decide a turn was finished only from a marker the agent writes, and some models leave it out, so a complete answer could get that nudge anyway.
A cloud session's turn now also counts as finished when its final reply is longer than 500 characters and isn't a context summary. A short note, or a turn that ends with no reply at all, is still nudged.
If a cloud session goes quiet after an API error (2026-11-06)
When a turn ends on a provider blip — an overloaded API, a dropped connection — the app retries it itself with a short "Please continue". On a cloud session whose previous run still held the machine, that send used to land in the history and be delivered to nobody, leaving the session idle. The retry is now HELD: it waits in the session's message queue and is delivered the moment that run finishes its turn, like a message you queued yourself, and it survives an app restart. Nothing is sent twice: the row the failed send wrote is taken back, so the history shows the retry once, where it ran.
If a session says its previous run is still working on its cloud machine
That means the session's last run never stopped: it is still working on its machine, and a new turn cannot start beside it. The app waited a few minutes before saying so. Send your message again once that run has finished; its work is safe. The app no longer cuts the connection to such a run just because it looked idle on this computer (2026-10-30), so you should rarely see this note.
If a launch ends by itself about fifteen minutes after it started
That is the app finishing a launch the controller never confirmed. When a launch fails the app tells the controller so it can record it; if the controller cannot be reached — it is down, or this computer is offline — the app keeps trying for fifteen minutes, then ends the session itself as failed and says so in a note. Nothing is left running and nothing is lost: retry the session. When the controller can be reached it still decides, and a refusal from it is never overridden.
While a launch is coming up and has produced no agent output it stays on "Setting up" even when the controller reports it idle, so a still-starting launch cannot appear in Needs You ahead of its first reply; one that ends as failed having produced nothing shows under Interrupted.
If a card says a machine purchase could not be confirmed after thirty minutes, the app could not tell whether a machine was already rented, so nothing was deleted or stopped, and the card names the reference to quote. It keeps checking and settles it once the provider's answer is clear.
If the machine is not on the image this app trusts
An Agent 37 machine can be created on any image the provider publishes, and an older one keeps the image it was born with however many times it is woken. The app fixes the image it uses and checks every machine against it — on a create, a clone of a saved starting point, a reuse, and every wake.
- A new machine is asked for by a pinned version, never the provider's floating name, so a release on the provider's side cannot change what your session runs on.
- A machine on any other image does not get a session. A new session passes it over and rents one on the trusted image, so the launch still starts; a session already bound to it does not start, and the reason appears in its transcript. Either way an alert names the machine and both images, and the machine is left in place — never stopped, released or deleted by this check.
- Its work still comes home, and the app can still clean it up. Waking it to bring work back, or to measure it before releasing it, is allowed; no session starts on it.
- A machine that will not say which image it runs is treated like a wrong one — refused for a session, and still able to hand its work home.
If a cloud machine runs out of disk space with finished session copies
Each session keeps its own copy of your project on the machine it ran on — about 2 GB each — and the
app frees a copy only once it can prove nothing in it changed after that session's work came home.
That proof skips the app's own housekeeping files inside the copy, which the machine writes there
forever: its route-relay log, its five-minute self-check, the install markers beside the project.
Without that, every finished copy looked changed and none was ever freed — 135 were left on four
machines while the disks ran to 89–94%. A copy an agent really did write into after its work came
home is still kept, and the log names it ([cloud-agent-copy-reap], kept=).
Related
- Starting a cloud session from a saved copy (project templates)
- Cloud sessions that keep working while the app is closed
- Cloud session zero-turn alarm — the card you get when a cloud session never produces an assistant reply.
Last verified 2026-11-09