FOLDING
@HOME

v8.5 Client Guide

Statue of Bastet, the Ancient Egyptian goddess associated with cats and protection from disease — the codename of the v8 Folding@home client
Bastet, the v8 client's codename.

This guide covers version 8.5 of the Folding@home client, codenamed "Bastet" after the Ancient Egyptian goddess associated with cats and protection from disease. v8 is a complete rewrite of the client, designed to simplify setup, lay a foundation for new features, and encourage community contributions.

If you've never installed Folding@home before, start with getting started for a high-level overview, then come back here for the v8.5-specific details.

Contents

What's new in v8.5

v8.5 is primarily a maintenance release. The user-visible addition is a new plot of user and team points on the Stats page; the rest is bug fixes. The full details are in the changelogs for fah-client-bastet and fah-web-client-bastet.

Changes from v7

If you're coming from v7, three things are different:

  1. Two pieces, not three. The v7 client had a backend (FAHClient), an advanced control panel (FAHControl), and a 3D viewer (FAHViewer) as three separate programs. v8 has just the backend (fah-client-bastet) and a browser-based frontend (fah-web-client-bastet) called Web Control. Web Control rolls all of FAHControl's features plus the 3D viewer into one interface.
  2. No more folding slots. In v7 you configured each compute resource as a "slot". In v8 you just tell the client which CPUs and GPUs to use, and the client allocates work to them automatically.
  3. Remote control via a Folding@home Account. Optional, but a big quality-of-life win if you fold on more than one machine. Sign in once, and you can monitor and control every machine you've registered — from any browser, including your phone, anywhere in the world.

Downloading the software

v8.5 is the current public release. Get it from the download page. Older v7 releases are still available, but using them is no longer recommended.

Installation

Folding@home v8 runs on Windows, macOS, and Linux. You only need administrator privileges to install the client; once it's installed, any user can fold.

Windows

  • Download the Windows installer from the download page.
  • Run the installer.
  • If Windows SmartScreen prompts, approve it.
  • The client starts in the background once the install completes.

macOS

  • Download the installer package.
  • Open it in Installer.
  • Enter your administrator name and password when prompted.
  • The client starts in the background once the install completes.
  • Copy the Web Control URL shown on the installer's last panel into a browser other than Safari — Safari blocks the local connection Web Control needs to talk to the client.

Linux (Debian / Ubuntu)

Download the fah-client_*.deb package and install it:

sudo dpkg -i fah-client_*.deb
sudo apt-get install -f   # pulls in any missing dependencies

The client runs as a systemd service named fah-client after install. You can check its status with systemctl status fah-client.

Linux (Fedora / RHEL / openSUSE)

Download the fah-client-*.rpm package and install it:

sudo dnf install ./fah-client-*.rpm        # Fedora / RHEL
sudo zypper install ./fah-client-*.rpm     # openSUSE

Same as Debian/Ubuntu, the client runs as a systemd service named fah-client after install.

Headless or server installs

The client itself doesn't require a graphical environment. After installing the Linux package, you can configure the client by editing /etc/fah-client/config.xml — see connecting headless machines below.

Using Web Control

The v8 client is controlled through a web browser. Open app.foldingathome.org — your browser will connect to the Folding@home client running on the same computer.

Web Control as it appears before a local client has been started — empty Machines list
Web Control without a local client.
Web Control after detecting the local client — the machine appears in the Machines list
Web Control connected to the local client.

Once the client is installed and running, the local machine appears on the Machines page after a short delay. (Note: v8.5 Web Control can only talk to v8.3 or newer clients.)

Optional: a Folding@home Account

Registering for a Folding@home Account lets you control every one of your machines from one place — including from a phone, even when you're away from the machine.

Account registration screen, showing fields for email and passphrase with options to auto-generate and reveal the passphrase
The Folding@home Account registration screen.

Registration needs a valid email address and a passphrase. (A passphrase is not the same as a passkey — the passphrase signs you into your account; a passkey ties returned Work Units to a donor identity. See Points, stats & passkey for the distinction.) Web Control can generate a four-random-words passphrase for you with the button; the button reveals it; copies it to the clipboard.

If your local client is already configured, your username, team, and passkey auto-fill (these three fields are optional during registration). After you click Register, an activation email is sent — click the link in it to finish setup.

Web Control login screen with fields for email address and passphrase
Web Control login screen.

Once you're logged in, the user icon in the top right opens your account settings, and every machine you've connected to the account appears on the Machines page.

Account settings

Account settings screen with Username, Team, Passkey, Cause, Node and Token fields
Account settings.

The Account section sets your Username, Team, and Passkey — these determine how your contribution shows up on the public stats. Points, stats & passkey covers what each one does.

The Cause setting tells the assignment server which research area you'd like to support most. The server will try to send you projects matching your preference but can't guarantee it (some Causes have more or less work available at any given time).

The Node and Token fields control how your machines connect to your account — see the next section for how to use them.

For changes to take effect, click the Save button in the top right. The Cancel button discards unsaved changes.

The Machines section lets you manage and configure your machines, including disconnecting them from your account. Changes take effect immediately. Warning: disconnecting a machine makes it inaccessible from your account — a manual reconnection is required to bring it back.

Connecting machines to your account

A machine running v8 connects to your account either automatically or manually:

  • Automatic. If the client is running on the same machine your browser is on, and the client isn't already linked to another account, signing in via Web Control connects it. Install the client, sign into your account once, and you're done.
  • Manual. Used when the local machine is already connected to a different account, or has no browser (see below). Use the link icon in Account Settings to change the connection.

Manually connecting headless machines

For machines without a graphical user interface (a home server, a Raspberry Pi running headless, etc.), you connect using the current account token. Copy the token from your account settings in any browser, then write it into /etc/fah-client/config.xml on the headless machine:

<config>
  <account-token v="<your account token>"/>
  <machine-name v="<a display name for this machine>"/>
</config>

Restart the client (sudo systemctl restart fah-client) and the machine appears in your account.

After you've added the machines, generate a fresh token in Account Settings. Only the most recent account token can add new machines, so rotating it prevents anyone else from using a leaked copy to attach their hardware to your account.

The account node (typically node1.foldingathome.org) is set automatically. It's possible to run your own node — advanced, but documented in the fah-node project.

The Machines page

Web Control showing the Machines page with a Fold button, a Pause button, and a list of folding machines with active Work Units
Web Control with a Folding@home Account — all your machines listed.

The Machines page is the screen you land on. Without an account it shows the local machine; signed in, it shows everything you've registered.

In the header are two large buttons: Fold and Pause. Fold starts folding on every machine in view; Pause stops them. If you're just getting started, configure your username and team before clicking Fold.

The body of the page lists each machine and any active Work Units (chunks of protein-folding simulation). For each WU you see progress, status, and a few action buttons on the right — including one to dump the WU (only do this when something is genuinely wrong; see fair-play rules) and one to open the 3D Protein Viewer.

Machine settings

Per-machine settings screen with Scheduling toggles and Resource Usage sliders for CPUs and GPUs
Machine settings.

Click the gear icon on a machine to open its per-machine settings. Note: when you're not logged into an account, this screen also includes the account fields (username, team, passkey) because there's no global account-settings page to put them on.

Scheduling

Controls when folding actually runs:

  • Only When Idle — fold only when nobody is using the keyboard or mouse.
  • While On Battery — allow folding on a laptop that isn't plugged in.
  • Keep Awake — prevent the machine from going to sleep so folding can continue.

Resource usage

The CPUs slider sets how many CPU cores Folding@home is allowed to use. You can change it at any time, but setting it too low while a WU is already running may cause that WU to fail — pause first if you want to drop the count significantly.

The GPUs section lists every supported GPU on your machine, each with its own enable/disable checkbox. GPU folding is much more efficient than CPU folding and usually earns substantially more points; if you don't want a particular GPU folding (say, the one your monitor is plugged into), uncheck it here. See troubleshooting if your GPU isn't being detected.

Advanced

Machine settings in advanced mode, showing Beta Projects toggle, Project Key, and Resource Groups options
Machine settings in Advanced Mode.

Click the lock icon in the bottom right of the Machine Settings screen to unlock the advanced controls. These are primarily for testing — experts only, and easy to misuse.

  • Beta Projects — allow assignment of in-testing projects. Earns fewer or unpredictable points; useful for catching client bugs before they ship to everyone.
  • Project Key — restricts the machine to a single project. Used by Folding@home staff to focus a test rig on a specific pre-beta project; not something most donors will ever set. Leave at zero to disable.
  • Resource Groups — split a machine's compute resources into multiple independently configured pools. Usually used with a Project Key to test a particular kind of work. It is possible to over-allocate resources this way, which can hang the machine.

The Stats page

Stats page showing your total points, team ranking, points-over-time plot, and milestone certificates
The Stats page, with the new v8.5 points plot.

The Stats page shows your point totals, ranking, and a chart of your contribution over time (new in v8.5). You can also download milestone certificates here — nice for sharing.

For how points are actually calculated, the QRB rules, deadlines, and the difference between passkey and passphrase, see Points, stats & passkey.

Projects and News

Projects page listing the research projects your machines are currently folding, with project IDs and brief descriptions
The Projects page.
News page showing recent Folding@home blog posts with titles and dates
The News page.

The Projects page lists the research projects your machines are actively folding — project IDs, brief descriptions, and which of your machines are working on what. The page is empty when you're not folding.

The News page mirrors the recent posts from the Folding@home blog so you don't have to leave Web Control to keep up with what the labs are publishing.

The Log Viewer

Log Viewer showing client log lines, with Search, Errors and Warnings filter checkboxes, Reset, and Follow controls
The Log Viewer.

The Log Viewer shows the running log of every folding simulation on your machine. Reading the log usually means caring about the technical details — you'll probably be sent here by a forum moderator or developer when something needs diagnosing.

  • Search — filter the log for lines matching a string.
  • Errors / Warnings checkboxes — show only error- or warning-level messages.
  • Reset — clear the filters.
  • Follow — auto-scroll as new lines arrive.

For common log-derived diagnoses (EUE failures, GPU not detected, "no work units available"), see troubleshooting.

The 3D Protein Viewer

3D protein viewer rendering a folded protein structure, with mode buttons and frame controls
The 3D Protein Viewer.

Click the icon next to any active Work Unit on the Machines page to open the 3D viewer. It renders the protein your computer is simulating in real time:

  • Mouse wheel zooms.
  • Left-click-and-drag rotates.
  • The 1, 2, and 3 buttons switch between three rendering styles (cartoon, ball-and-stick, surface).
  • As the simulation progresses it snapshots the protein into frames — the arrow buttons cycle through them. If no frames are available yet the counter reads 0 of 0.

Dark Mode

Web Control in dark mode, with a dark background and light text
Dark mode.

Account Settings → Appearance toggles between light and dark themes. Most users find dark mode easier on the eyes in low-light environments.

Getting help

If something isn't working, try these in order:

Open-source contribution

The v8 client is open source. Anyone can help improve it: report issues, suggest features, or contribute code via the GitHub repositories:

Before filing a new issue, please make sure you've researched the problem and that it isn't already tracked. We get more feature requests than we can implement, so ask for help on the forum or Discord before opening a feature-request issue.

Pull requests are welcome — smaller, focused PRs with clean, well-tested code are much more likely to be accepted than large bundles of changes. See also our broader open-source page for the supporting libraries (GROMACS, OpenMM, MSMBuilder, Copernicus) the project builds on.