# Settings and profile

> Reference for all controls in the Hyperclay Local popover, the Options menu, your sync key, and your profile in files.

Source: https://hyperclaylocal.com/docs/settings/

Hyperclay Local has no separate settings window. You control serving and sync from the switches in the [popover](https://hyperclaylocal.com/docs/popover/), manage individual folders from each folder card's `⋯` menu, and configure your account, profile, AI editing, and helper permissions from the **Options** menu in the popover footer.

## Popover switches

The **THIS COMPUTER** section of the popover (or the status area when you have a single folder) has two switches that apply across all folders:

| Control | Labels and states | What it does |
| :--- | :--- | :--- |
| **Serving** switch | **Turn server on** / **Turn server off**. Readouts: **Serving**, **Starting…**, **Not serving**, **Can't serve** | Starts or stops the local HTTP servers for all of your folders. |
| **Sync** switch | Replaced by **Connect sync →** until a key is saved. Readouts: **Not synced**, **Sync off**, **Sync on**, **Syncing**, **Synced as @`<username>`** | Starts or stops syncing with `hyperclay.com`. |

## Options menu

Click **Options** in the bottom bar of the popover to open the app menu:

| Menu item | What it does |
| :--- | :--- |
| **Change Personal Folder…** | Opens **Select folder containing your malleable documents** to switch the folder served at `localhost:4321`. |
| **AI Editing** | Checkbox (enabled by default) that turns [AI editing](https://hyperclaylocal.com/docs/guide/ai-editing/) on or off across all served documents. Also available in the system tray menu as **Enable AI Editing** / **Disable AI Editing**. |
| **Helper Programs** | Lists approved [helper programs](https://hyperclaylocal.com/docs/programs/) with a **Remove** action for each program, plus **Forget All Document Permissions**. |
| **Profile…** | Opens the profile view to configure **Use my profile in files**. |
| **Sync Key…** | Opens the form to connect or replace your `hyperclay.com` API key. |
| **Refresh Teams** | Checks `hyperclay.com` immediately for changes to your team memberships and roles (also checked automatically every 5 minutes). |
| **View Sync Logs** | Opens the `sync` logs folder in your file manager. |
| **View Error Logs** | Opens the `errors` logs folder in your file manager. |
| **Autostart on Login** | Checkbox that launches Hyperclay Local automatically when you log in to your computer. |
| **About Hyperclay Local** | Shows the installed version of Hyperclay Local. |
| **Quit** | Waits for open tabs and workspace frames to finish saving, then quits the app. |

## Sync key

Open the sync key form by clicking **Connect sync →** on the home view or **Options** > **Sync Key…**. One API key is used across the entire app for both your personal folder and all [team folders](https://hyperclaylocal.com/docs/guide/team-folders/).

1. Click **Get API key** to open `https://hyperclay.com/dashboard` in your browser and create a key.
2. Enter your account name in **Username** (placeholder: `Your hyperclay.com username`).
3. Paste your key into **API Key** (placeholder: `hcsk_...`).
4. Click **Connect & Enable Sync** (the button reads **Connecting...** while verifying, or click **Cancel** to go back).

If the key field is blank, the form shows **API key is required**. If `hyperclay.com` refuses the key, the form shows **Invalid API key** or the server's error message. Accepted keys are encrypted with your operating system's credential store and saved in [`settings.json`](https://hyperclaylocal.com/docs/files/).

## Profile in files

Open **Options** > **Profile…** to control whether Hyperclay Local supplies your name and identity to documents you open locally.

When **Use my profile in files** is turned on, each served folder exposes your identity as `document.people.me` on `/_/meta` (restricted to that folder's own origin). Documents that use the [people plugin](https://clayjs.com/docs/plugins/people/) read this endpoint to show who is editing or leaving comments.

### When sync is connected

When a sync key is connected, Hyperclay Local uses the public profile from your `hyperclay.com` account and caches it so it works offline:

- When on, the view shows **Using your Hyperclay account profile: `<name>`**.
- When off, the view shows **When on, files use your Hyperclay account profile: `<name>`**.
- Click **Change name on Hyperclay** to edit your profile on the web, then click **Refresh profile** to pull the updated name into Hyperclay Local.
- If your account profile has not been fetched yet, the view reads: **Your account profile isn't available right now. Files won't record a name until it is.**

### When sync is not connected

When you use Hyperclay Local without a sync key, you can set a local display name stored on your computer:

1. Turn on **Use my profile in files**.
2. Enter your name in **Display name** (placeholder: `Your name`).
3. Click **Save name**, then click **Done**.

The first time you save a local display name, Hyperclay Local generates a persistent 22-character ID for your profile on this computer. Local display names must follow three rules:

- Cannot be empty (**Enter a name.**)
- Must be 120 characters or fewer (**Use a name of 120 characters or fewer.**)
- Cannot be an email address (**Use a name, not an email address.**)

Turning **Use my profile in files** off stops the app from supplying your name to documents. As the profile view notes: **Turning this off stops the app supplying your name. Names already saved in files stay there.**

### Profile error messages

If checking or saving your profile fails, the profile view shows one of these messages:

| Message | What to do |
| :--- | :--- |
| **Couldn't reach Hyperclay to check your account. Try again when you're online.** | Reconnect to the internet and try turning the profile switch on or clicking **Refresh profile** again. |
| **Your account changed while checking. Try again.** | Click **Refresh profile** to retry. |
| **Update the server to use your account profile.** | Wait for `hyperclay.com` to be updated to a version that supports account profiles. |
| **Hyperclay rejected your sync key. Reconnect it in Options > Sync Key.** | Open **Options** > **Sync Key…** and enter a valid API key. |
| **Couldn't save your profile settings.** | Check that your app data folder is writable and try again. |