When a cloud session won't start

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, and until now the app found out how slow only after it had already rented the machine. It also let every session you started upload at the same time, so a group of sessions started together competed for one connection and could all fail together — while telling you only that the session "couldn't finish starting up".

Both of those are fixed. The app now looks at your project before it rents anything, sends one project upload at a time, and when it does stop, it tells you why.

Where to find it

There is 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 vague "couldn't finish starting up" it used to show, naming the size, the file count and the way out rather than leaving you to guess.

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 has to wait does its waiting before its own upload begins, so waiting costs it none of the time it has to upload with.
• A session that cannot start says so, and rents nothing. If your project is so large that uploading it would take longer than a session is allowed to spend on it, the session stops before any machine is created, and the message tells you the size, the file count, and what to do next.
• A session that waited too long says so too, and cleans up after itself. If the sessions ahead of it take longer than the longest wait this app will hold, a session that never gets its turn stops, removes the machine it had already started, and says how long it waited — so nothing is left running with nothing to do.
• A session tells you what its upload is doing, while it is doing it. You are told when a session starts waiting for its turn and how many are ahead of it, when its turn comes and how long it waited, and if it gives up on sending just the changed files and sends the whole project instead. Nothing has failed in any of those moments, and none of them is a stopping point.
• A session that fails to start no longer leaves a machine behind. A machine whose start failed before any agent ever ran on it is now removed outright, instead of being stopped and left for someone to clean up later.
• A machine that will not stop is reported, not retried forever. Parking a machine is how this app stops paying for it, and a machine counts as stopped only once the app has read it back as stopped — asking the provider to stop it is not the same thing, and the provider accepts the request a moment before the machine is actually down. If a machine refuses to go down on three separate attempts, the app stops trying and raises one notice in your inbox naming the machine, so a machine that is still costing money is something you are told about rather than something you find on a bill.
• 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 you no extra money and no setting; the change only prevents spending that used to happen on uploads that could not finish. A session that waits for its turn is a session that would otherwise have competed for the same connection.

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 the project's files from the repository instead of uploading them — which is both faster and not subject to the upload time budget at all.

For agents

• The upload is measured before the machine is created, against the ship row's own budget, using the app's measured upload rate. The decision, its thresholds and its copy are fixed by .claude/memory/contracts/cloud-launch-admission-contract.md.
• A project with no file list (a non-git folder) cannot be measured and therefore always proceeds — an unmeasurable upload is never treated as an oversized one.
• Project uploads run one at a time process-wide, and the unit that takes a turn is the LAUNCH, not one road of it: whichever way a launch sends its files — a saved-copy delta, a delta cut against a base fetched from the project's own repository, a fallback to the whole tree, or the whole tree outright — it holds the one permit for the whole of it. (An earlier version of this page said a saved-copy delta "is small by construction and deliberately does not take a turn"; measured 2026-10-01, a delta cut against a fetched repository base was 2,668 files / 152.3 MB, and nine of them ran at once and all died together.)
• A machine removed by a failed start is one this process created, holds the only id for, never persisted a remote for and never ran an agent on. A machine with a live co-tenant is never touched by that road.
• A stop is confirmed by reading the box until its state settles, and only a settled stopped (or a machine that no longer exists) may be reported as stopped. archiving is transitional, not down: a box mid-archive is still running and still billing, and listing it as down would licence skipping a stop on a live machine. A box that fails to stop BOX_REPARK_LIMIT parks in a row is retired from the park sweep and raises ONE deduped "still billing" card per box id, cleared by whatever road finally confirms it down. The re-park loop this replaced ran 312 times across three boxes in one night with nothing telling a person.

Related

• Starting a cloud session from a saved copy (project templates)
• Cloud sessions that keep working while the app is closed