---
title: When a cloud session won't start
---

# 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.

## 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 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.
- **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.
- Full project uploads run one at a time process-wide. A saved-copy delta is small by construction
  and deliberately does not take a turn.
- 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.

## Related

- [Starting a cloud session from a saved copy (project templates)](cloud-session-templates.md)
- [Cloud sessions that keep working while the app is closed](cloud-returned-work.md)