Self Hosting

CoCalc Star on a local VM

Install CoCalc Star inside a local Ubuntu VM for private, fast, offline-friendly work on your own computer.

Why run CoCalc Star on your own computer?

If you tried CoCalc and want the same kind of browser-based workspace on your own hardware, a local VM is a good fit. It is especially useful when you want:

This setup runs CoCalc inside an Ubuntu virtual machine on your computer. You open CoCalc from your normal browser on the host computer.

For a personal computer, the recommended CoCalc Star local VM path is Lima. Lima runs headless Linux VMs, is scriptable, supports localhost forwarding, and does not push you toward a graphical desktop VM.

Install Lima first. On macOS:

brew install lima

On Ubuntu Linux, install QEMU support first:

sudo apt-get update
sudo apt-get install -y --no-install-recommends ovmf qemu-system-x86 qemu-utils

Then install Lima using Homebrew on Linux if you already use it, or download the current Lima binary archive from https://github.com/lima-vm/lima/releases.

Then install CoCalc Star:

curl -fsSL https://github.com/sagemathinc/cocalc-ai/releases/download/cocalc-star-stable/install-cocalc-star-local-lima.sh \
  | COCALC_STAR_LIMA_SHARED_DIR="$HOME/cocalc-star-scratch" bash

This creates or starts a Lima VM named cocalc-star, installs Ubuntu 24.04, forwards CoCalc to http://localhost:8170/, installs CoCalc Star inside the VM, and prints the local setup URL. Project sessions, terminals, chat, and Jupyter use the same localhost origin through CoCalc's built-in project proxy. The optional COCALC_STAR_LIMA_SHARED_DIR value is a host folder that becomes /scratch inside projects. For example, a host file $HOME/cocalc-star-scratch/data.csv is visible in projects as /scratch/data.csv. The installer creates the host folder if it does not exist. Edit the path before running the command, or remove the environment variable if you do not want host file sharing.

After install, open http://localhost:8170/, create the first account, create a project, and test a terminal plus a Jupyter notebook.

The general local setup is:

  1. Install a VM app that can run Ubuntu 24.04.
  2. Create an Ubuntu VM with enough disk and memory for your projects.
  3. Forward a local port on your computer to port 80 inside the VM.
  4. Open CoCalc at a localhost URL such as http://localhost:8170/.

Using localhost is better than opening the VM's private IP address directly. Browsers treat localhost as a trusted local address, and it is easier to bookmark and remember.

Which VM app should I use?

Use the VM app that fits your computer and comfort level. If you do not already have a preference, start with Lima.

If Lima does not fit your platform or workflow, use Parallels on Mac, VirtualBox on Windows, and KVM/QEMU on Linux as practical manual alternatives. On Mac, choose UTM if you want a free desktop VM app.

Customizing the Lima VM

The Lima installer accepts environment variables passed to bash at the end of the install pipeline.

For example, to use 16 GiB RAM, 8 CPUs, and a 200 GiB disk:

curl -fsSL https://github.com/sagemathinc/cocalc-ai/releases/download/cocalc-star-stable/install-cocalc-star-local-lima.sh \
  | COCALC_STAR_LIMA_MEMORY=16GiB COCALC_STAR_LIMA_CPUS=8 COCALC_STAR_LIMA_DISK=200GiB COCALC_STAR_LIMA_SHARED_DIR="$HOME/cocalc-star-scratch" bash

The default memory is host-aware. On a typical laptop it uses a reasonable fraction of system RAM instead of Lima's small default.

The shared directory setting is initial-install only. Lima reads this setting when the cocalc-star VM is created; rerunning the installer does not change an existing VM's shared directory.

The commands below delete the VM and all data stored only inside it, including CoCalc project files, the database, and local backups. Before replacing the VM, back up important data outside it and verify that backup. Keeping the host shared folder preserves only the files stored in that folder, not the VM's project HOME directories.

After protecting the guest data, use these commands to remove the local VM before reinstalling with the new shared-directory setting:

limactl stop cocalc-star
limactl delete cocalc-star

Do not delete $HOME/cocalc-star-scratch unless you also want to remove the host files that were visible as /scratch.

Networking choice

Pick one of these access patterns:

  1. Best: http://localhost:8170/

    Configure your VM app to forward host port 8170 to guest port 80. This gives you a local browser URL and avoids public internet exposure.

  2. Simple fallback: http://vm-private-ip/

    Many VM apps show a private VM IP address, such as 192.168.x.y or 10.x.y.z. You can often open that directly from your host browser. This is simple, but it is less polished than a localhost URL.

  3. Avoid for local-only VMs: public HTTPS with https://sslip.io

    The public CoCalc Star installer can set up automatic HTTPS for a public VM. That is the right path for cloud servers, not for a VM that only exists on your laptop.

What to expect

A local VM install is private to your machine unless you deliberately expose it to your network. You can use it without depending on CoCalc's hosted service. If you are offline, local project tools keep working, but internet-dependent features still need internet access.

The default project image includes Python, pip, uv, Jupyter, LaTeX, and common scientific Python packages. You can use pip install or uv pip install from a project terminal for additional packages such as PyTorch.

You are responsible for the VM's disk, backups, operating-system updates, and any data you store there. If the VM is important, back it up like any other important local computer.

Practical notes