Starting a cloud session from a saved copy (project templates)

What it is

A cloud session runs an agent on a machine the app rents instead of on your own computer. To do that it has to put your project there first: it uploads the files and installs the project's dependencies. On a large project that takes minutes, and it happens again every time.

A project template is that work done once and kept. After a project has run its first cloud session, the app saves the machine's disk — your code at that moment plus the dependencies it just installed — under a name your account holds. Every later cloud session for that project starts from that saved copy, so it only has to send what has changed since, and it can start working in seconds instead of minutes.

Where to find it

There is no screen to open: it works on its own whenever you start a cloud session. Its one switch is in Settings.

Turning it off

Settings → Session Behaviour → Start cloud sessions from a saved copy. It is on by default. Switching it off restores the original behaviour exactly: every cloud session uploads the whole project and installs its dependencies, with nothing saved and nothing reused.

How it behaves

What you will notice

The first cloud session of a project starts as it does today; later ones start from the saved copy.

• The first cloud session of a project does a full upload and install. It establishes the starting point for a later saved copy.
• Shortly afterwards, the saving happens on its own. It uses a separate machine that is created, filled, saved, and then stopped — a background job you do not have to wait for and will not see running. The next session for that project benefits from it.
• Later sessions start faster and send less. Only the files that changed since the saved copy travel, plus anything you deleted, which is removed on that machine to match your project. The session says so in one line — how many changed files it is uploading and how big they are.
• A size the session shows you while it is working is an ESTIMATE of your project, not the number of bytes it is sending. The wording says so — "an estimate of the project on this computer" — because the two differ a lot: a saved copy sends only what changed, and a project whose machine can fetch it from your repository sends none of the project from your computer at all. When that happens the session's line says so in those words instead of claiming an upload.
• Each session still gets its own machine. A template is a starting disk, never a shared machine; two sessions never see each other's work.
• If anything about the saved copy is wrong or missing, the session quietly does the old thing — a full upload — and writes one line saying so. You will never be unable to start a session because of this feature.
• A saved copy is refreshed when its contents or dependencies change. The app compares the current project with fingerprints recorded at capture. When a fingerprint could not be read, it treats that comparison as unknown and still sends the changes needed for this launch.

What it costs

Two things, both small and both bounded:

• Storage for the saved copy. It is held by the machine provider for as long as the name exists, which is indefinitely — a saved name has no expiry. Removing it releases that storage. The provider publishes no separate storage price; its published rate is one number per machine size per hour, which it describes as the whole bill.
• One extra machine start per build, not per session. A build runs once when a project first needs a saved copy and again when the project's dependencies change. Your account's start limit is measured in starts per minute, hour and day, and builds are run one at a time so that a burst of session launches stays inside it.

How it decides to build

A build is asked for at the end of a session that had to upload the whole project — the moment the app knows the project has no usable saved copy. One build runs at a time across the whole app. A project is not rebuilt more than once every thirty minutes, and a project whose build failed is retried only the next time it is needed, never in a loop.

For agents

• The saved copy is a named snapshot on the machine provider. Names the app creates carry the prefix amc-tpl-; the app never creates, replaces or removes a name that does not, so your own snapshots in the same account are untouched.
• The app never saves a machine that has run an agent. The separate builder may briefly receive a project-specific read-only repository key to fetch the base. Before saving the disk, it proves that key is gone and that no non-template .env secret file remains in the project tree. If either proof fails, it skips the saved copy.
• A session's work is compared against the state its machine actually began with — the saved copy plus the changes sent on top — never against the saved copy's own older base. Getting this wrong would hand you back changes you had already made as though the agent made them.
• Contracts: cloud-session-project-templates-contract.md is the promise; cloud-sessions.md is how it works.

Related

What happens at the other end — the work a cloud session brings back, how it is tested and landed, and how your project's secret files travel to the session's machine and are kept out of returned commits — is on Your cloud session's work comes home and lands itself. Running a session on another machine you own, rather than one the app rents, is SSH Remote; and keeping a session on your own computer in its own private copy of your project is Session isolation.