# Team folders

> Sync each Hyperclay team you belong to into its own local folder with its own localhost port, all using one sync key.

Source: https://hyperclaylocal.com/docs/guide/team-folders/

Each [team](https://hyperclay.com/docs/teams/) you belong to on hyperclay.com syncs into its own folder on your computer and runs on its own local port, all using the same sync key as your personal folder.

## One sync key for all folders

You only enter one sync key (`hcsk_...`) for the entire app, either when clicking **Connect sync →** in the [popover](https://hyperclaylocal.com/docs/popover/) or under **Options** > **Sync Key…** (see [Sync with hyperclay.com](https://hyperclaylocal.com/docs/guide/sync/)).

When you connect your key, Hyperclay Local discovers every team you belong to automatically. It re-checks your teams every 5 minutes while sync or your profile is active, and you can check immediately at any time by choosing **Options** > **Refresh Teams**. When you are added to a team, Hyperclay Local shows a notification titled **Added to `<team>`**.

If your sync key is revoked or stops working, every synced folder pauses with **paused: reconnect** (**Your sync key no longer works. Reconnect to resume.**) and the top of the popover shows **Sync key no longer works.** with a **Reconnect →** button. Entering a new key resumes all of your folders.

## Set up a team folder

When you are an editor on a team that has not been set up on this computer yet, its row in the popover reads **not on this computer** (**You're an editor on `<Team>`. Set up a folder to sync it here.**) with a **Set up →** button.

**Step 1: Open the team setup view**

Click **Set up →** on the team's row in the popover (or click the **Added to `<team>`** notification). The setup view shows the suggested **FOLDER**, the port it **OPENS AT** (`localhost:<port>`), and the number of files and total size that will download (`<n> files, <size> will download.`).

**Step 2: Choose an empty folder inside your home folder**

Hyperclay Local suggests a new folder at `~/hyperclay/<team-username>` (or with `-2` through `-99` suffixes, or `~/hyperclay-teams/<team-username>`), marked `(new)` when it does not exist yet. To pick a different location, click **Choose another folder…**.

A team folder must start empty (**This folder isn't empty. A team folder has to start empty.**), though `.DS_Store`, `Thumbs.db`, `desktop.ini`, and `.hyperclay` are ignored. If you pick a folder that already has files, Hyperclay Local offers **Use `<path>` instead** to create a subfolder inside it. The folder must also be inside your home folder, must not overlap another served folder, and must have enough free disk space for the download.

**Step 3: Confirm trust and start syncing**

Documents in a team folder come from that team's editors and run in your browser on its local port. Check **I trust `<username>`'s editors**, then click **Set up & sync**.

If you quit Hyperclay Local while a team folder is downloading its initial files, setup picks up where it left off next time.

## Ports for team folders

Your personal folder always uses port `4321`. Each team folder is assigned the first free port from `5432`, `6543`, `7654`, `8765`, and `9876`, falling back to a free port between `49152` and `65535` if those are taken. You can move a team folder to another port if its port is in use (see [Folders and ports](https://hyperclaylocal.com/docs/folders-and-ports/)).

## Viewer role on a team

Only team editors sync a local folder:

- **When you join as a viewer**: the team gets no folder and no local port. Its row in the popover is dimmed, shows **viewers use the site** (**You're a viewer on `<Team>`. Viewers open team documents on hyperclay.com.**), and offers **hyperclay.com ↗** (**Open on hyperclay.com**). Viewer teams are not listed in the tray menu.
- **When your role changes from editor to viewer**: if you already set up a team folder and your role is later changed to viewer, sync pauses with **paused: you're a viewer** (**You're now a viewer on `<Team>`. Your files are still here and still served at `localhost:<port>`. Sync resumes if you're made an editor again.**). See [Offline, paused and viewer states](https://hyperclaylocal.com/docs/sync-states/).

## Disconnect or remove a team folder

Open the team folder's `⋯` menu in the popover (or its submenu in the tray):

- **Disconnect…**: stops syncing with the team while keeping the folder on your computer and served at `localhost:<port>`. The card then reads **local only · was `<team>`**.
- **Remove Folder…**: stops syncing and stops serving `localhost:<port>`, while leaving the folder and its files on your computer.

See [Disconnect or remove a folder](https://hyperclaylocal.com/docs/disconnect/) for details.
