Terminal

SSH access to projects

Connect to cocalc.ai projects from a computer or another CoCalc project using SSH.

SSH access on cocalc.ai

SSH gives command-line tools on your computer direct access to a CoCalc project. You can run remote commands and use standard tools such as ssh, scp, sftp, and rsync.

The legacy ssh.cocalc.com gateway belongs to the previous cocalc.com architecture. Commands such as ssh [email protected] do not connect to cocalc.ai projects. Each cocalc.ai project instead receives a managed SSH route, which the CoCalc CLI writes into your local ~/.ssh/config.

Connect from your computer

Open Project Settings → SSH in the target project. The panel shows commands for the current site and project.

Install the CoCalc CLI using the CLI quickstart, which includes Linux/macOS and native Windows PowerShell instructions.

Configure the project, replacing the example project id:

cocalc --api https://cocalc.ai project ssh-config add \
  -w 00000000-0000-4000-8000-000000000000

When run in an interactive terminal, the CLI starts browser login automatically if you have not signed in yet. Approve that login in your browser. The command then:

  1. creates or reuses ~/.ssh/id_ed25519;
  2. installs its public key in the target project;
  3. installs the Cloudflare SSH transport helper when needed; and
  4. writes a managed host entry to ~/.ssh/config.

Connect using the project id as the host alias:

ssh 00000000-0000-4000-8000-000000000000

The key and SSH config remain usable after CLI login expires. The account session is needed for setup, not for each SSH connection.

Copy files

After setup, file-transfer tools use the same host alias:

scp ./local-file 00000000-0000-4000-8000-000000000000:~/
scp 00000000-0000-4000-8000-000000000000:~/remote-file ./
rsync -a ./local-directory/ \
  00000000-0000-4000-8000-000000000000:~/remote-directory/

rsync must be installed at both ends. If scp or sftp reports a missing SFTP server, install openssh-sftp-server in the project image.

Transfer individual files with SFTP

After the SSH setup above, open a local terminal in the folder containing a small test file named local-file.txt. On Windows, use PowerShell with the OpenSSH client, which includes sftp. Connect using the same alias as ssh, replacing the example project id:

sftp 00000000-0000-4000-8000-000000000000

OpenSSH reads the managed Host entry, including its real HostName, user, key, and transport settings. If you configured a custom --alias, use that alias instead. If setup used a custom --config file, pass its path to sftp -F PATH_TO_CONFIG ALIAS.

At the sftp> prompt, enter these commands without copying the prompt itself. Choose unused destination names: put and get can overwrite files.

lpwd
pwd
ls
put local-file.txt sftp-upload-demo.txt
ls sftp-upload-demo.txt
get sftp-upload-demo.txt downloaded-file.txt
bye

lpwd shows the local directory; pwd and ls describe the remote project. put reads a local file and writes its remote destination; get reads a remote file and writes its local destination. Confirm the uploaded file appears in the remote listing and compare the downloaded file with your original. Use lcd to change the local directory and cd to change the remote one; quote paths containing spaces. Type help for the installed client's commands.

A graphical SFTP client must support the route and authentication settings in the generated SSH configuration, including ProxyCommand when present. Entering the project-id alias in a generic hostname field alone is insufficient; do not assume the application imports OpenSSH configuration automatically. If a connection fails, inspect sftp -v ALIAS and the SSH troubleshooting steps below. For a complete upload/run/download workflow through the CoCalc CLI, see remote analysis.

Connect from one CoCalc project to another

Do not run cocalc auth login inside a collaborative project. That would store a broad, long-lived account session in a filesystem shared with the project's collaborators.

Instead:

  1. Open Project Settings → SSH in the target project.
  2. Choose Configure project-to-project SSH.
  3. Select the source project that will initiate connections.
  4. Confirm the operation with fresh authentication.
  5. In a terminal in the source project, run ssh TARGET_PROJECT_ID.

CoCalc reuses ~/.ssh/id_ed25519 when the source already has one. Otherwise, it creates a new deploy key and stores its private key as the encrypted SSH_PRIVATE_KEY project secret. It authorizes only the public key on the target and writes the route in the source project. Your CoCalc account session is never stored in either project.

Everyone with filesystem access to the source project can use its deploy key. Only select a source whose collaborators should receive access to the target. To revoke access, delete the corresponding project SSH key from the target project's SSH settings.

Automated course setup

If a script in the project containing a .course file must connect to every student project:

  1. Open the .course file and select Configuration.
  2. Find SSH to course projects.
  3. Check Allow this course project to SSH to every student project and the shared project.
  4. Complete the fresh-authentication prompt.

CoCalc creates one deploy key in the course project, authorizes it in every active student project and the shared project, and writes a managed SSH entry for each target. A deployment script can then use a project id directly:

ssh STUDENT_PROJECT_ID 'python3 ~/setup.py'
rsync -a ./course-environment/ STUDENT_PROJECT_ID:~/course-environment/

The CoCalc CLI is already installed inside CoCalc projects, but this course workflow does not run cocalc auth login and does not store an instructor's account session in the collaborative course project.

Use Synchronize SSH access after adding or restoring student projects, or after a target project moves to another host or region. CoCalc also attempts to configure newly created student and shared projects automatically. If that attempt happens after fresh authentication has expired, project creation still succeeds; open Course Configuration and synchronize SSH access again.

Unchecking the option removes the managed public key from all known student projects and the shared project, and removes their managed SSH config entries. The deploy key itself remains in the course project so it can be reused if the option is enabled again.

Everyone with filesystem access to the course project can use this key and thus receives full shell access to every configured target. Only enable the option when every course project collaborator should have that access.

The course manager who enables the option owns the project-specific public-key entries and must also synchronize or disable them. This guard prevents a second manager from accidentally leaving the original manager's key authorized.

Troubleshooting