> ## Documentation Index
> Fetch the complete documentation index at: https://neroli.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud

> Snapshot a session into cloud, keep it running, and bring it back.

Cloud handoff starts with a snapshot.

Neroli captures the current session, including conversation context, file edits,
workspace state, and the information needed to recreate it in a cloud runtime.
The session can keep going there, then come back local when you want it.

<Frame caption="Cloud changes the location of a session. The workspace, panes, conversations, and changed files remain the product object.">
  <div className="not-prose rounded-xl border border-dashed border-gray-300 bg-gray-50 p-8 text-center text-sm text-gray-600 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300">
    Placeholder image: a session snapshot carrying conversation, edits, workspace state, panes, and provider context from Local to Cloud and back.
  </div>
</Frame>

## Why this matters

Your work belongs to the workspace, not a single provider UI or runtime. That
means you can:

* start locally and move a supported session to cloud
* run many remote sessions in parallel
* bring cloud work back to your Mac
* keep using supported providers without locking the work to one place
* stay local-first by default and use cloud as the accelerator

## What moves

Neroli handoff is designed around continuity:

* conversation context
* current file edits
* workspace and branch state
* provider/session metadata for supported panes
* enough environment context to resume the work
* status and recovery information if the move needs attention

If something cannot move cleanly, Neroli surfaces that before you end up in the
wrong session or a blank provider pane.

## Make cloud sessions usable

Cloud needs setup, environment, and network access.

<Steps>
  <Step title="Describe setup">
    Add the commands that make the cloud runtime ready: install dependencies, build generated assets, or prepare toolchains.
  </Step>

  <Step title="Add environment variables">
    Store the variables the cloud runtime needs. Mark secrets as secrets instead of committing them.
  </Step>

  <Step title="Choose network access">
    Keep access restricted by default. Open only the domains the task needs.
  </Step>

  <Step title="Test before relying on it">
    A broken setup script turns cloud into a waiting room. Test the environment before moving important work.
  </Step>
</Steps>

## The handoff loop

| Stage          | What Neroli is doing                      | What you should watch                                                    |
| -------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| Local          | The session is running on your Mac.       | Work can use local panes, files, and devices.                            |
| Snapshot       | Neroli captures the session state.        | Conversation, edits, workspace state, and provider context are prepared. |
| Cloud          | The supported session continues remotely. | Run more agents, watch status, and respond when needed.                  |
| Bring back     | Neroli syncs the cloud result local.      | Recovery messages, pending sync, or conflicts are surfaced.              |
| Continue local | The work is back in the workspace.        | Review, edit, run automations, or merge.                                 |

If something fails, Neroli tracks the recovery path: retry moving to cloud,
reconnect the cloud session, retry moving back to local, complete a pending
local sync, or ask for manual intervention.

<Info>
  Terminal, browser, diff, and file panes can follow cloud sessions. Simulator and preview panes are local-only because they depend on your Mac.
</Info>

## Setup once

Cloud works best when the workspace already knows how to prepare itself.
Automations and cloud setup reinforce each other:

* setup should be deterministic
* verification should be one command
* secrets should be explicit
* network access should be intentional
* cleanup should be predictable

Next: use [Review](/docs/review) to decide what comes back from cloud and what ships.