Move projects between hosts

What a project host move does

Moving a project to another host changes where the project runs and where the project's host-local data lives. CoCalc uses backups to transfer the project to the destination host, restores it there, and updates the project-host assignment.

Use a move when a project needs more RAM, GPUs, a different region, a quieter host, or a host that a specific group can access.

Before moving

Check these items before starting the move:

1. The destination host is running or can be started.
2. The user is allowed to place projects on the destination host.
3. The destination has enough disk and RAM for the project.
4. The source host has a recent backup, especially if the source host is stopped or deprovisioned.
5. The user understands that /tmp files and previous host-local snapshots will not follow the project.
6. SSH access may need to be configured again after the move.

If the move changes backup region, CoCalc restores from the current backup region, creates a new backup in the destination region, then switches the project's backup region after that backup succeeds.

During and after the move

Watch the move progress. If the source host is unavailable, the move may use the most recent backup. After the move finishes, open the project, verify files, start the needed notebooks or services, and check that collaborators can still work.

Agent notes

For browser work, open the project settings or project file flyout and use the host picker. For CLI work, inspect the host and project first:

cocalc host list --json
cocalc host get <destination-host>
cocalc host projects <source-host> --all

If automating a move, prefer explicit destination host ids. Do not rely on implicit placement unless the task is genuinely "pick an available host". Always mention the /tmp, snapshot, backup freshness, SSH, and region consequences before advising a user to move important work.