Folders and ports

Hyperclay Local serves one personal folder plus one folder for each team 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 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 for details.

Folder rules#

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

How ports are assigned#

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

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 so local scripts and helper 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.
• 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.