Project host lifecycle actions

Lifecycle states

A project host has two related lifecycles:

1. the CoCalc host record, access policy, billing policy, and project placement metadata
2. the provider resources that actually run projects, such as the VM, disk, network identity, daemon processes, and runtime software

Start provisions or starts the provider machine and then waits for bootstrap, software lifecycle, and daemon health to settle. Stop shuts down the machine while keeping the host record and recoverable provider state. Restart reboots the running machine. Deprovision removes provider resources. Delete removes the host record after deprovisioning, or before a provider machine was ever created.

Start, stop, and restart

Use Start when the host is stopped or deprovisioned but should run projects again. Start can be blocked by billing enforcement, missing connector availability for self-hosted machines, active lifecycle work, or provider errors.

Use Stop when you want to stop paying for active compute while keeping the host configuration. CoCalc may ask whether to back up projects first. During an active start or restart, Emergency stop can appear when the provider supports stopping the machine and the host is in a stoppable state.

Use Restart for runtime drift, daemon problems, or settings that require a machine restart. Reboot is graceful when the provider supports it. Some providers also expose a hard reboot, which is more disruptive and should be a maintenance-window action.

Check operation status before retrying

The CLI commands host start and host restart return a queued operation unless --wait is supplied. When waiting fails, read the complete error. A recovery error can say that the provider request was acknowledged but reboot completion and application readiness are unverified because a previous boot or host-session identity was unavailable. In that case, the request was sent and may still be in progress; the failed operation is not proof that the provider did nothing.

Inspect the current host state, bootstrap details, and recent logs before issuing another start or restart. Replace HOST_ID with the existing host:

cocalc host get HOST_ID
cocalc host bootstrap-status HOST_ID
cocalc host logs HOST_ID --tail 200

Use the returned state and the original error to decide the next step. A host being online still requires a check of the project and workload you need.

Browser disconnects and project runtime

Closing a browser tab disconnects that browser. Projects with a browser-idle policy can also stop automatically after browser presence has been absent for the configured time. Check the Free project runtime banner inside the project for its timeout; do not assume every project has the same policy.

Running code in a notebook, terminal, or agent does not itself supply browser presence. A public share or a collaborator with only viewer access does not keep this runtime running. After a browser-idle stop, open the project in an authenticated CoCalc browser with runtime access before retrying automatic services. If automatic starts are disabled, use the project's Start button as directed by the error message.

A browser-idle stop preserves project files. Save results to files instead of relying on variables or other state held only by a running process. A stopped project, a stopped host, and a browser disconnect are different conditions; check project and host status before deciding how to recover. Host maintenance, provider interruptions, and billing enforcement can interrupt availability independently of the browser-idle policy.

Deprovision and delete

Deprovisioning is destructive for provider resources. It removes the cloud machine and attached provider resources. It does not mean "hide from the UI" or "pause billing for a minute"; it is a lifecycle boundary. Use it when changing settings that require a fresh machine, retiring the host, or recovering from provider drift that cannot be reconciled safely.

Deletion is the final cleanup. It is available after deprovisioning, or before provisioning created provider resources. Deleted hosts do not expose further destructive actions.

Maintenance operations

The host action menu also includes Backup projects, Drain, and sometimes Cancel backups. Backup projects creates project backups for provisioned or running projects on the host. Drain is for removing active work from a host before maintenance. Cancel backups is only offered during the backup stage of a host operation.

For CLI maintenance, host drain <host> moves projects; --force instead clears their host assignments without copying project data. --allow-offline permits moves that may rely on stale backups. Without --wait, the command returns a queued operation. After a failure, inspect the operation and run cocalc host projects <source-host> --all: earlier moves may already have completed. Verify saved files and the required workloads at their destinations before treating the maintenance as complete.

Agent notes

Before running lifecycle commands, check active host operations, project backups, assigned projects, billing enforcement, and provider capabilities. Prefer deprovision over delete when provider resources still exist. Do not advise deprovisioning a host with important unbacked work.