Install CoCalc Star

What CoCalc Star is

CoCalc Star runs a shared CoCalc site in one Docker container, with agent chat, project files, terminals, and real-time collaboration. Built-in editors include Jupyter and LaTeX. It is free and runs with Docker Desktop on macOS or Windows, or Docker Engine with cgroup v2 on Linux.

All of its state (accounts, projects, settings, certificates) lives in one Docker volume. Upgrading means running a newer image with the same volume; removing the container and the volume removes all of its data.

Quick start on your own computer

1. Install Docker Desktop (macOS or Windows) or Docker Engine with cgroup v2 (Linux) and start it. Allocate at least 4 CPUs and 16 GB of memory to Docker, with at least 50 GB of free disk space for its volume.
2. In a terminal (on Windows, in PowerShell), run:

docker run -d --name cocalc-star --restart unless-stopped --privileged --cgroupns=host -v cocalc-star:/var/lib/cocalc -p 8170:80 -e COCALC_STAR_HTTP_PORT=8170 sagemathinc/star

3. Follow the first start, which takes a few minutes:

docker logs -f cocalc-star

4. Open the printed link that starts with http://localhost:8170 and create the first admin account.
5. Create a project and check that Jupyter, a terminal, and LaTeX work.
6. To add collaborators, share the signup URL that the same log prints after "Invite another user with this signup URL". Like the admin link, it starts with http://localhost:8170, so it opens only on this computer. To invite people who use other computers, run Star on a server with a domain, as described next.

On a server with a domain

Point a DNS name at a Linux server with Docker Engine and cgroup v2, open TCP port 443 (port 80 is optional), and pass the domain:

docker run -d --name cocalc-star --restart unless-stopped --privileged --cgroupns=host -v cocalc-star:/var/lib/cocalc -p 443:443 -p 80:80 -e COCALC_STAR_DOMAIN=star.example.com sagemathinc/star

Certificates are obtained and renewed automatically. Set COCALC_STAR_ACME_EMAIL to give the certificate authority a contact address.

First admin account

The first start prints a single-use link for creating the first admin account. Print it again with:

docker exec cocalc-star star bootstrap-link

If it was already used, or you lost access to the admin account, create a new single-use admin link (valid for 24 hours):

docker exec cocalc-star star admin-link

Upgrade

docker pull sagemathinc/star
docker rm -f cocalc-star

Then run the same docker run command you installed with. The new container reinstalls the new release over the existing volume and logs upgrading CoCalc Star from <old> to <new>. Running projects stop during the upgrade and can be started again right away. To go back, run the previous image tag with the same volume.

Back up

Stop the container for a consistent copy of the volume:

docker stop cocalc-star
docker run --rm -v cocalc-star:/data -v "$PWD":/backup ubuntu tar -C /data -czf /backup/cocalc-star-backup.tar.gz .
docker start cocalc-star

Keep backups off the machine that runs Star, and test restoring one into a fresh volume before relying on it.

Remove CoCalc Star

This deletes CoCalc Star and all of its data:

docker rm -f cocalc-star
docker volume rm cocalc-star
docker rmi sagemathinc/star

Star writes no files outside Docker. One thing outlives the container on Linux hosts that use AppArmor (for example Ubuntu): the cocalc-star-podman profile described below stays loaded in the kernel until the host restarts. It only applies to Star's bundled Podman. To unload it right away:

echo -n cocalc-star-podman | sudo tee /sys/kernel/security/apparmor/.remove

Why the container is privileged

Each project runs in its own rootless container with its own storage inside the CoCalc Star container, so the outer container needs --privileged and --cgroupns=host. Docker is how Star is distributed; the isolation between users and projects is inside the container. On Linux hosts that restrict unprivileged user namespaces with AppArmor (Ubuntu 23.10 and later), the container loads a small AppArmor profile named cocalc-star-podman that gives its bundled Podman the same permission the distribution gives its own Podman.

When to use Star

Use Star for a lab, course, GPU box, agent sandbox, or small team that wants collaborators in the same browser-based CoCalc workspace on hardware they control. Star is one machine: it is not high availability or scale-out.

Star is for people you invite: signing up requires a registration link. Every project has internet access; Star does not include the network restrictions that public CoCalc sites apply to free accounts, nor their free-tier project limits: anyone can create as many projects as they like, and each project gets 8 GB of memory and a 20 GB disk quota by default. Only the machine itself limits how many run at once. An admin can change these by editing the Free membership tier in the admin settings. Disk quotas need Linux 6.7 or newer; on older kernels, including Docker Desktop's current WSL2 kernel on Windows, projects have no disk quota and share the volume's space.

Product boundaries

• Use CoCalc.ai for projects hosted and run by SageMath, Inc.
• Use CoCalc Plus for a local single-user install.
• Use CoCalc Star for a shared site in one Docker container.

For a larger private deployment, talk with us.

Map the connections

Installing CoCalc on your machine does not prevent applications from contacting external services. Review the credentials and endpoints selected for AI tools, remote kernels, package downloads, and user code as part of your deployment.

Troubleshooting

docker exec cocalc-star star status
docker exec cocalc-star star doctor
docker exec cocalc-star star smoke
docker exec cocalc-star star logs hub

star smoke creates a test account and project and checks Jupyter, LaTeX, and terminals end to end.

Agent notes

When helping someone install Star:

1. Confirm Docker is installed and running (docker info), with at least 4 CPUs and 16 GB of memory allocated to it and at least 50 GB of free disk space for its volume. Linux requires cgroup v2.
2. Use the one-line docker run commands above unchanged; they work in macOS and Linux shells and in Windows PowerShell.
3. For a public server, the domain must already resolve to the server and port 443 must be reachable before starting the container.
4. If the first-admin link is gone, use star admin-link; do not delete the volume to start over unless the user wants to lose their data.
5. After install, verify that the first project starts and Jupyter, a terminal, and LaTeX work.