Instructions

Before you start

• A Linux computer with CryoSPARC v5. It must be x86_64 with RHEL, Rocky, or Alma 8+, Ubuntu 20.04+, or Debian 10+. You need a login on it and about 1.1 GB of free space in your home folder.
• Your CryoSPARC account. You need the address you open CryoSPARC at, your email, and your password.
• An OpenAI or Anthropic API key. You need one of them. Create an OpenAI key at platform.openai.com/api-keys, or an Anthropic key at platform.claude.com/settings/keys. The provider charges your account for what the agents use.
• For model building only. Install PyMOL and ChimeraX on the same computer. Phenix and Rosetta are optional and add refinement. To build a model from a sequence, you also need a CryoZeta account from em.kiharalab.org.

Set up CryoPilot

1. Log in to the CryoSPARC computer

   Open a terminal on the computer where CryoSPARC runs. If it is a remote computer, connect to it with this command. Replace you@cryosparc-computer with your own login.

   $ssh you@cryosparc-computerCopy

   Run the commands in steps 2 and 3 on this computer.

2. Install CryoPilot

   $curl -fsSL https://cryopilot.vercel.app/install.sh | shCopy

   The installer asks a few questions. Press Enter at each one to keep the default answer. When it finishes, it reports the install to this website so that we can count installs. To skip this, see Install without the install count.

   When it finishes, open a new terminal on the same computer. Then check the install:

   $cryopilot --versionCopy

   It prints cryopilot and the version number. This first command also unpacks the program, which takes less than a minute.

3. Start CryoPilot

   $cryopilot startCopy

   The first time, it asks you to choose a password of at least 8 characters. This is a new password for CryoPilot only. Do not reuse your CryoSPARC password.

   When CryoPilot is ready, it prints this:

   CryoPilot is running (pid 12345, started 2026-11-02 10:00, up 0 min).
   
       Open:  http://localhost:8790

   CryoPilot keeps running after you log out, so a long run does not stop when you close the terminal. Always use cryopilot start. Without start, CryoPilot stops when the terminal closes.

4. Open CryoPilot in your browser

   On your laptop, open a new terminal and run this command. Use the same login as in step 1, and leave this terminal open while you use CryoPilot.

   $ssh -L 8790:localhost:8790 you@cryosparc-computerCopy

   Then open http://localhost:8790 in the browser on your laptop and sign in with the password from step 3.

   If your browser runs on the CryoSPARC computer itself, skip the ssh command.

5. Complete the setup screens

   CryoPilot shows six screens the first time you open it.

   License agreement

   Read the terms, then click Agree.

   Choose an API key

   Choose OpenAI or Anthropic, paste your API key, then click Continue. Both agents use models from that provider by default.

   Sign in to CryoSPARC

   Enter your email and password. For CryoSPARC URL, enter the address you open CryoSPARC at, for example http://localhost:61000. Then click Continue.

   Sign in to CryoZeta

   Enter your CryoZeta account and click Continue. If you have no account, click Skip for now. You need it only to build a model from a sequence.

   Choose a processing guide

   Keep General guide, then click Continue.

   Ready to start

   This screen lists the modeling programs that CryoPilot found. Turn on Remember passwords on this computer if you do not want to enter your key and passwords again after each restart. Then click Open CryoPilot.

6. Create a project

   Click New project, enter a title such as the name of your sample, and click Create project. A project holds all the sessions for one sample.

7. Start a reconstruction

   Click Reconstruction, keep New data selected, and fill in the form.

   Dataset

   Choose Movies, Micrographs, or Particles. Enter the folder or glob on the CryoSPARC computer, for example /data/krios/movies/*.tif. For particles, also enter the RELION .star file. For movies, add the gain reference, defect file, and EER settings if your data has them.

   Microscope

   Enter the pixel size and total dose. Voltage and spherical aberration start at 300 kV and 2.7 mm. Change them if your microscope is different.

   Sample

   Enter the particle diameter and symmetry. Use C1 if you do not know the symmetry. The description and molecular mass are optional.

   CryoSPARC project

   Keep the title. For Location, enter a folder that CryoSPARC can write to, for example /data/cryosparc/projects. CryoSPARC creates the project folder there.

   In the message box at the bottom, type your goal and press Enter. For example: Reconstruct a high-resolution map of the whole complex.

   CryoPilot creates the CryoSPARC project and starts work. Each step appears in the session as it happens, and CryoPilot reports back when it is done or needs you.

   You can close the browser and the ssh connection, and the run continues. To check it later, run the ssh command from step 4 again and open http://localhost:8790.

What else you can do

Continue a session that stopped

Open the session, type continue in the message box, and press Enter.

Continue an existing CryoSPARC project

Click New session, Reconstruction, and then Existing project. Choose the project, type your goal, and press Enter. CryoPilot works in a new workspace and reads the jobs already in the project. It does not change them.

Build a model

Click New session, then Modeling. Attach a map with the + button, or choose a map that CryoPilot lists. Describe what you want and press Enter.

Share CryoPilot with your lab

Run these two commands on the CryoSPARC computer:

$cryopilot stopCopy

$cryopilot start --lanCopy

CryoPilot prints the links to share. Everyone signs in with the CryoPilot password. They share your projects, API key, and CryoSPARC account, and they can use a terminal that runs as your user. Give the password only to people you trust with your account, and use this only on a network you trust.

Use a Claude model

If you chose OpenAI during setup, add an Anthropic API key in Settings under Accounts. Then choose the model in the message box when you start a reconstruction or modeling session.

Install without the install count

When an install or update finishes, CryoPilot tells this website the version and whether it is a new install or an upgrade. Vercel Web Analytics records this with the country, and without your login or IP address. To skip it, use this install command instead, and set CRYOPILOT_NO_ANALYTICS=1 before you run cryopilot update:

$curl -fsSL https://cryopilot.vercel.app/install.sh | CRYOPILOT_NO_ANALYTICS=1 shCopy

Install without the installer

Download the binary to the CryoSPARC computer and make it executable. Then run it in place of cryopilot in the steps above:

$chmod +x cryopilot-0.3.5-linux-x86_64Copy

$./cryopilot-0.3.5-linux-x86_64 startCopy

Everyday commands

Run these on the CryoSPARC computer.

cryopilot status

Shows whether CryoPilot is running and the address to open.

cryopilot stop

Stops CryoPilot. Agents that are running stop too.

cryopilot restart

Stops CryoPilot and starts it again.

cryopilot log -f

Shows the log as it is written. Press Ctrl-C to leave.

cryopilot password

Changes the CryoPilot password. Run cryopilot restart after it.

Update CryoPilot

CryoPilot checks for a newer version once a day and tells you when there is one. Click Update in the app, then Restart when it is ready. Or run this command on the CryoSPARC computer, and then cryopilot restart:

See what changed in the changelog. Your projects, sessions, and settings stay. CryoPilot checks the download and starts the new version before it replaces anything, so a failed update leaves your current version as it was. The update then removes the files of older versions. It needs about 1.1 GB of free space while it runs. The Restart button waits until no agent is running.

Version 0.3.4 or earlier

These versions cannot update themselves. Run these commands on the CryoSPARC computer once:

$cryopilot stopCopy

$curl -fsSL https://cryopilot.vercel.app/install.sh | shCopy

$cryopilot startCopy

Turn off the daily check

The check reads a list of releases from this website and sends nothing else. To turn it off, set this before you start CryoPilot:

$export CRYOPILOT_NO_UPDATE_CHECK=1Copy

If something goes wrong

cryopilot: command not found

Open a new terminal. The command is available only in terminals that you open after the install.

The page does not open in your browser

Check that the ssh command from step 4 is still running on your laptop. Then run cryopilot status on the CryoSPARC computer.

Port 8790 is already in use

Another program uses that port. Start CryoPilot on a different one:

$cryopilot start --port 8791Copy

Then use 8791 in place of 8790 in the ssh command and in the address.

Could not sign in to CryoSPARC

Check that CryoSPARC is running. Then check that the address, email, and password are the ones you use in your browser.

The Sign in again screen

It appears after a restart if CryoPilot did not keep your key and passwords. Enter them again. To skip this next time, turn on Remember passwords on this computer.