Use project hosts

What project hosts are for

A project host is compute capacity that can run CoCalc projects. On hosted CoCalc, project hosts are CoCalc-managed or cloud-backed capacity; users cannot attach an arbitrary local computer or VM as a host. Hosts have access to project-level credentials such as backup passwords, so direct user-controlled hosts are only appropriate in self-hosted Star, Launchpad, or Rocket deployments. CoCalc Star includes one local project host by default; Launchpad and Rocket expose the broader operator workflows for managing hosts.

Use project hosts for heavier workloads such as long-running research computations, courses, or agent sandboxes.

For a comparison with managed VMs and remote notebook kernels, see Choose compute for research.

The host is not just a label. It controls where the project filesystem lives, where project processes run, where host-local snapshots are stored, what runtime software is installed, which backup region is used, and which users are allowed to place projects there.

Create or choose a host

1. Open the project host administration area.
2. Configure a cloud provider. In CoCalc Star this is normally already the bundled local host; in self-hosted Launchpad or Rocket, configure a cloud provider or self-hosted connector.
3. Refresh the provider catalog if needed.
4. Choose a machine type, region, disk size, and lifecycle policy.
5. Start the host and wait for bootstrap to finish.
6. Move or create projects on the host when it is ready.

Use enough disk space for runtime images and project data. Very small disks can fail during image bootstrap or package installation.

Access and placement

Private hosts are available to the owner and delegated users. A delegated User can create or move projects onto the host. A delegated Manager can also start and stop the host, manage access, configure the per-project RAM cap, and place projects there.

Admins can publish a host into the Public shared pool by assigning a host tier. Users whose membership grants that project-host tier, or a higher tier, may place projects there without delegated host access.

Project RAM cap

The host Project resource policy has an optional per-project RAM cap. With the cap blank, a private host uses a default derived from its reported RAM when available, with room left for host services. A public shared-pool host keeps the project's normal RAM entitlement.

See Manage project host access and RAM for the defaults and how to plan for several projects running together.

CPU sharing

Projects can use otherwise-idle CPU capacity within the host's project pool. Managed project hosts reserve some CPU capacity for host services; those cores are not available to projects even when the services are idle. When several projects need CPU at the same time, their shared-compute priorities determine their relative shares. Higher priority helps under contention; it does not reserve particular cores.

To use several cores at once, your program must run work in parallel. The number of cores visible to a program does not guarantee that all of them will be available to that program throughout a computation.

GPU access

On an NVIDIA GPU host, GPU-enabled projects receive access to all of the host's GPUs. Projects on the same host can use the same devices, so coordinate concurrent jobs with other host users and check available GPU memory before starting a large workload.

GPU memory is separate from the project RAM cap. Increasing that cap does not increase the memory on a GPU.

Moving projects

Moving a project between hosts is a data operation, not a cosmetic setting. CoCalc moves through backups and restore. Files in /tmp are discarded, previous host-local snapshots are discarded after the move, and SSH access must be reconfigured after the move. If the destination region differs, the backup region can change after a successful new backup.

Long-running work

For research jobs, scheduled automation, or agent sandboxes, use a host with enough CPU, RAM, disk, and restart behavior for the workload. Keep important state in project files, a database, or another durable location rather than only inside a process.

Agent notes

When helping with project hosts:

1. Determine whether the user is on hosted CoCalc, Star, Launchpad, Rocket, or Lite. Lite does not use project hosts. Hosted CoCalc does not allow arbitrary local user machines as hosts. Star normally has exactly one bundled local project host.
2. Open the hosts page with the hosts.open docs action when browser context is available.
3. For CLI inspection, start with:

cocalc host list --json
cocalc host get <host>
cocalc host projects <host> --all
cocalc host metrics <host>
cocalc host bootstrap-status <host>

4. Before recommending a move, check source host status, backup freshness, destination access, destination RAM/disk, region changes, and whether /tmp or host-local snapshots matter.
5. Do not assume the current bay is authoritative. Route host operations by the host's owning bay and project operations by the project's owning bay.

Why this matters in CoCalc

Project hosts make CoCalc more than a shared web editor. They let the project own real compute, run persistent services, use cloud machines economically, and give agents a stable Linux environment to work in.