All about the Project Settings tab.
The text for Title and description for a project can be changed at any time.
Title and Description fields are both used when searching for matching text under Projects. If you have several projects, it can help to add hashtags to your project descriptions for topics you want to return to quickly.
Why Add Upgrades?¶
There are many reasons that you might want to have an upgraded project.
- To give your project access to the internet. For example,
- To download a software package from the internet.
- To use Github/Bitbucket/Gitlab with your project.
- To download datasets into your project.
- To connect to your project with SSH.
- To get extra storage space (both RAM and disk space).
- To get more compute resources.
- To have a higher idle timeout threshold. (See What is an “idle timeout?”.)
You can share upgrades with any project that you are a collaborator on. You must be a collaborator (or owner) to update a project.
For details on paid subscriptions, see Subscription and Pricing Information. Paid subscriptions start at $14 per month.
View Current Resources¶
You can view upgrades for the current project and current resource use under Project usage and quotas. Here’s an example for a project with no upgrades added (note the warning banner that appears if the project does not have Member Hosting or Internet Access):
The “Adjust Quotas” dialog is where you add upgrades you have just purchased to your own project.
Note: If you want to upgrade student projects for a CoCalc managed course, that is done in the .course file. (See the Upgrading student projects section in the teaching guide.)
You can enter any values that do not exceed available upgrades. This example continues by adding as much in the way of resources as possible to the current project. You can remove upgrades at any time and apply them to other projects.
When you click Adjust Quotas…, a dialog like the following appears. The screenshot shows numbers for a project that has not been upgraded. Available upgrades show what the numbers would be if you just purchased a Standard Plan and have not applied any upgrades yet:
Here are the two most important upgrades. You will probably want to apply these to any project you are working on actively:
Member hosting is added by checking the “Enable” box next to the upgrade.
There are two types of projects: “free projects” and “member projects”. Free projects run on heavily loaded Google preemptible VM instances. These are randomly restarted by Google at least once every 24 hours. Often, these computers will house over 150 simultaneously running projects.
Member-hosted projects run on machines which are much less loaded and are reserved for paying customers only. On member-hosted projects, commands execute more quickly, and CPU, memory and I/O heavy operations run more quickly.
Internet access is added by checking the “Enable” box next to the upgrade. This upgrade allows you to:
- Originate connections to external sites, for example to install packages from internet sites for Python and R, or to clone code from GitHub.
- Send email from a project, for example, to invite people without a CoCalc account to collaborate on a project via email, or to allow @mentions in a project to send out emails.
Max All Upgrades¶
Clicking Max All Upgrades will add as much as possible from available upgrades:
Then clicking Save Changes will apply the changes and restart the project if settings have changed:
Next in the Project Settings window is the section for hidden and deleted projects, which do not appear in the normal project list (the list you get when you click Projects at upper left).
If the current project is neither hidden nor deleted, you will see this:
Hiding a project¶
If you click Hide Project, the button changes:
And now if you click the Projects button at upper left, you will have a checkbox that lets you view hidden projects. The checkbox only appears if there are hidden projects.
Clicking Unhide Project instantly makes the project visible in the normal project list again.
Deleting a project¶
Note: No files are actually deleted by this operation. Only visibility of the project in the project list is changed. If you need to permanently delete information that you accidentally copied into a project, contact firstname.lastname@example.org
If you click Delete Project, the button changes:
Click Yes, please delete this project to confirm, and the screen changes again:
Note the warning banner that appears at the top.
The project will not appear in the normal project list for you and all collaborators on the project.
And now if you click the Projects button at upper left, you will have a checkbox that lets you view deleted projects. The checkbox only appears if there are hidden projects.
Clicking Undelete Project instantly makes the project visible in the normal project list again for you and all collaborators on the project.
For addtional detail, see the blog posting Using SSH with CoCalc.
You can connect to a CoCalc project from your local desktop using SSH (Secure Shell) and you can upload/download files between your computer and CoCalc using the SSH protocol, with
rsync command line tools. You must have owner or collaborator status on a project for SSH access to be permitted.
When logging into a project with
ssh, make sure the project is running. If the project is stopped, or is in the process of starting up, you may get a message of ‘Permission denied’ or be prompted for a password.
SSH authentication uses a pair of keys, a private key and a public key. Each key is stored in a separate file. For example, a private key might be in the file
id_ed25519 and the matching public key in
id_ed25519.pub. In general, private keys are not distributed, while public keys are uploaded to remote systems.
On OS X, and Linux, key pairs are stored in
~ indicates your user’s home directory. Use the
ssh-keygen command to generate a key pair. (You can do
man ssh-keygen from a terminal for details on the command.)
CoCalc does not support manual editing of the authorized_keys file for SSH authentication.*
To make sure you really connect to CoCalc, you can check the fingerprint of the SSH Host Key.
Configuring SSH Keys for a Single Project¶
This section assumes you have created an SSH key pair as described above.
Open the project Settings tab (wrench icon) for the project you want to access.
Look for the section “SSH Keys” at lower left.
Click “Add an SSH Key”.
Enter a title for the key in the Title field. Specify a title that is meaningful to you for the key pair you are using, for example “Sample Key for TESTPROJ”.
Copy the public key into the Key field. To do this, open the file for your public key on your local computer. For example, if you are using macOS or Ubuntu, you could open a terminal and type something like the following, depending on the name of your public key file:
Use your mouse to select the contents of the key file, then copy and paste it into the Key area.
Click “Add SSH Key”. Your key is now saved for that project.
The user for the SSH connection is the project id without the hyphens. (Why? Because the project id is not a valid Linux username.) The hostname is
ssh.cocalc.com. Look for “Use the following username@host:” in the “SSH Keys” section of project status for a string you can copy and paste. For example, if the Project id is:
then the SSH username@host will be:
To login from your local computer, use a command equivalent to the following:
On macOS or Linux, you can specify a host alias in
~/.ssh/configto avoid having to explicitly pass the project id as above. For example, the following lines in
Host CCPROJ Hostname ssh.cocalc.com User 2507078b6e5b43da809a0073f1196181 IdentityFile ~/.ssh/id_ed25519
will allow you to log into the your project from your local computer with the command:
You can also specify a single SSH key pair under Account Tab to use with all your projects.
Each CoCalc project has an owner and zero or more collaborators.
Owner and collaborators all appear in a project under the identity of “user” and home directory of
There is no difference in the Linux identity,
regardless of the CoCalc account that is signed in.
Owner and collaborators can read anything in the project, and write, delete, and modify anything except backups. They can add and remove other collaborators, but cannot remove the owner.
Although the owner and all collaborators appear in a project with the same Linux user id, there are two ways to see which CoCalc account was used for certain actions in a project:
- The project activity log.
- Time travel for files edited using the CoCalc frame editor.
The “Current collaborators” section of the Project Settings page shows the names of the owner and all collaborators. Here you can remove collaborators, including yourself. It does not allow you to remove the owner.
Current collaborators are also shown in the Projects list. You can use the latter to remove yourself as collaborator from several projects at once.
At the Add new collaborators dialog, you can type in a person’s name or email address. CoCalc will search its database of known users and show you possible matches.
- After you select a name, don’t forget to click “Invite User.”
- The user must accept the invitation to be added as a collaborator.
It is generally better to use an email address. The reason is that some CoCalc users have multiple accounts.
If there are no matches for an email address, then you can send an invitation for the user to start using CoCalc. You can modify the standard email. The default invitation has useful links to make it easier for the other person to start using CoCalc.
Sometimes, you’d rather give someone read-only access. In CoCalc, this is called “sharing” with non-collaborators. See share for how to share a file.
Caution: if you are using CoCalc for course management with a .course file, add students under the Students tab of the .course file, and NOT as collaborators. That way, they get their own projects, separate from the instructor project. On the other hand, it is common practice to add teaching assistants as collaborators in the instructor project.
Here is a screen capture of the Project control section. Along with project statistics, it has two buttons and a menu, discussed below.
Restart Project and Stop Project¶
What happens when a project restarts?
- All computations will be stopped.
- Good News: You don’t lose unsaved files.
- You do lose any information (state of variables/processes) in RAM.
- However, anything in files, as long as it’s moved from the browser to the web servers (in most cases, at most a few seconds of information), is permanently saved to disk already in the database, and will not be lost.
- When the project starts back up, even if the files on disk are in an older state, the files you see yourself editing in your browser are new with nothing lost. Those files will then be updated on disc very shortly.
- On the other hand, project code, i.e. the CoCalc software environment, is updated.
To make all this happen, click “Restart Project…”. Another button appears, to confirm the choice.
Click “Restart Project Server”, and restart initiates.
It normally takes about 30 seconds to restart a project. It may take another 10 seconds or so after the Files list is visible for terminal processes, etc. to be available.
You can also stop and restart a project in two separate steps. Why would you stop a project and then restart it, rather than simply restarting it in a single step?
- If you want CoCalc to move the project to another server, stopping it first and then restarting it allows CoCalc to select a different, possibly less-loaded server.
- If you don’t want any of your project’s processes to run until you explicitly restart the project, you have to stop the project.
Clicking “Stop Project…” causes the “Stop Project Server” button to appear, to confirm your choice:
The CoCalc software environment is updated frequently. The collection of installed utilities, compilers, libraries, packages, etc. is called the compute image.
A running log of regular updates to the environment is the default software updates list.
You may want to revert to an older environment, or try a new environment that is about to be released. To change the software environment to a different compute image, use the “Selected Image” menu. The exact list of available images will change from time to time.
Once you have selected an image, click “Save and Restart”.
Note: Don’t forget to reset your image to “Default” after you are finished working with an alternate image.
Any time you run a Sage worksheet (.sagews file) there are two processes involved in your project:
- the Sage worksheet server process - one of these is enough to serve any number of running worksheets
- the Sage worksheet client process - there will be one of these for each worksheet that is running in the project
It can be helpful to restart the Sage worksheet server if you have changed the default version of Sage, for example with
Note that restarting the Sage worksheet server will not affect worksheets that are already running.
Occasionally, it may be useful to restart the Sage worksheet server if worksheets are not executing properly, followed by restarting individual Sage worksheet(s). You might do this as a less drastic step than restarting the entire project.
CoCalc by default provides an interface to Jupyter notebooks that has been rewritten to support multiple users, TimeTravel, and other enhancements. For more information, see the CoCalc blog article on the Jupyter rewrite. There may be occasions when you may want to run the Classical Jupyter server. The most common reason is to use interactive widgets, which are not supported in the CoCalc Jupyter notebook.
The “Project Settings” page offers two ways to run the Classical Jupyter server code, shown below. For more information and some important caveats, see Classical versus CoCalc.
Plain Jupyter server¶
Starting the Plain Jupyter server opens a new browser tab with usual files listing. Opening a notebook from the Jupyter server tab opens another browser tab.