# Folders and ports

> How Hyperclay Local assigns folders and local ports for your personal account and teams, and how to change them.

Source: https://hyperclaylocal.com/docs/folders-and-ports/

Hyperclay Local serves one personal folder plus one folder for each [team](https://hyperclaylocal.com/docs/guide/team-folders/) you set up on your computer. Every served folder gets its own local port on `127.0.0.1` so you can open and edit your documents at `http://localhost:<port>`.

## Personal folder

When you launch Hyperclay Local for the first time, step 1 in the popover is **Choose a folder** ("Any folder works, even an empty one. It starts serving as soon as you pick it.").

1. Click **Choose folder…** in the popover.
2. In the **Select folder containing your malleable documents** picker, select a folder inside your home folder.
3. The button changes to **Starting…** and turns on the local server automatically.

Your personal folder always uses port `4321` and serves at `http://localhost:4321`.

To move your personal folder to a different path later, click **Options** in the popover footer and select **Change Personal Folder…**. Your previous folder stays on disk untouched, and the new folder takes over `http://localhost:4321`. You cannot remove the personal folder with **Remove Folder…**.

## Team folders

When you [connect sync](https://hyperclaylocal.com/docs/guide/sync/) with `hyperclay.com`, teams where you are an editor appear in the popover as **not on this computer** with a **Set up →** link. Each team account can have at most one folder on your computer.

1. Click **Set up →** on the team's row.
2. Under **FOLDER**, review the suggested path (marked **(new)** if it does not exist yet) or click **Choose another folder…** to open the **Choose a folder for `<team>`** picker.
3. Check **I trust `<username>`'s editors**.
4. Click **Set up & sync** to create the folder, start its local server, and download the team's files (`<n> files, <size> will download.`).

By default, Hyperclay Local suggests `~/hyperclay/<team-username>`. If that path already exists and is not empty, it suggests `-2` through `-99` suffixes or `~/hyperclay-teams/<team-username>`.

Teams where you are a viewer do not get a local folder or port. See [Offline, paused and viewer states](https://hyperclaylocal.com/docs/sync-states/) for details.

## Folder rules

Every folder you choose for your personal account or a team must follow these rules:

| Rule | What happens if broken |
| :--- | :--- |
| Must be inside your home folder (and cannot be your home folder itself) | Shows **Folder not available**: **Choose a folder inside your home folder.** |
| Cannot be inside or contain another served folder | Shows **Folder not available**: **That folder overlaps `<path>`.** |
| A team folder must start empty (ignoring `.DS_Store`, `Thumbs.db`, `desktop.ini`, and `.hyperclay`) | Shows **This folder isn't empty. A team folder has to start empty.** and offers **Use `<path>` instead** |
| Your disk must have room for a team's initial download (file size plus 10% and 50 MiB) | Refuses setup until enough disk space is free |

## How ports are assigned

Hyperclay Local binds each folder's server to `127.0.0.1` on its assigned port:

| Folder type | Port assignment |
| :--- | :--- |
| Personal folder | Fixed at `4321` |
| Team folders (1st through 5th) | First free port from `5432`, `6543`, `7654`, `8765`, `9876` |
| Additional team folders (or if ladder ports are busy) | Random free port between `49152` and `65535` |

When allocating a port for a team folder, Hyperclay Local skips `4321`, skips any port already assigned to another folder, and tests that the port is free on `127.0.0.1`.

While folders are running, Hyperclay Local records each folder's path and port in [`served-roots.json`](https://hyperclaylocal.com/docs/files/) so local scripts and [helper programs](https://hyperclaylocal.com/docs/programs/) can look up the active port.

## Open a folder's address

When the **Serving** switch is on, each folder card shows its address as a clickable `localhost:<port>` link. While the server is off, the card reads **starts at :`<port>`**.

- Click `localhost:<port>` on the card or click **Open workspace** to open the folder in the [workspace window](https://hyperclaylocal.com/docs/guide/workspace/).
- Open the folder card's `⋯` menu (or the system tray submenu for that folder) and click **Open in Browser** to open `http://localhost:<port>` in your default browser.
- Click **Copy Address** in the folder card's `⋯` menu to copy `http://localhost:<port>` to the clipboard.

Visiting `http://localhost:<port>/` at the top level in a browser redirects to the workspace using a one-time ticket valid for 60 seconds and sets a session cookie for that port.

## Resolve port conflicts and change ports

If another program on your computer is already using a folder's port, the popover's serve status reads **Can't serve**, the folder card shows **Not served. Another program has :`<port>`.**, and the system tray menu marks the folder **(port `<port>` in use)**.

On a team folder, the card shows two buttons:

- **Retry**: Checks the current port again after you stop the other program.
- **Use port `<nextPort>`…**: Offers the next free team port. Clicking it opens a confirmation dialog titled **Move `<folder>` to localhost:`<nextPort>`?** ("Links and bookmarks to localhost:`<port>` will stop working. The htmlclay wire command finds the new port by itself.") with **Move** and **Cancel** buttons.

> [!NOTE]
> Your personal folder always uses port `4321` and cannot be moved to another port. If port `4321` is in use by another program, stop the other program and click **Retry**.