# Limits

> Design boundaries, folder rules, file size caps, and non-goals for Hyperclay Local.

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

Hyperclay Local is a single-user local host and sync client for your computer. The boundaries below cover what the app serves, how it updates, and what sync and helper features accept.

## Server and app boundaries

- **One personal folder plus one folder per editable team**: Hyperclay Local serves your personal folder on port `4321` plus one folder for each team account where you are an editor (assigned from ports `5432`, `6543`, `7654`, `8765`, `9876`, or a random port from `49152` to `65535`). You cannot add extra standalone local folders beyond your personal folder and your team folders, and you cannot change the personal folder's port from `4321` (see [Folders and ports](https://hyperclaylocal.com/docs/folders-and-ports/) and [Team folders](https://hyperclaylocal.com/docs/guide/team-folders/)).
- **Home-folder boundary and no overlapping folders**: Every served folder must sit inside your home directory (never the home directory itself, and never outside it) and cannot sit inside or contain another served folder.
- **No HTTPS**: Every local server runs plain HTTP on loopback (`127.0.0.1`).
- **In-place updates require a writable install**: Writable macOS `.app` installs, per-user Windows installs, and writable signed Linux AppImages download and install updates in place. Copies running from a read-only folder, a macOS DMG or App Translocation path, a machine-wide Windows install, or a development build cannot replace themselves in place and show a download link to `https://hyperclaylocal.com/` instead (see [Updates](https://hyperclaylocal.com/docs/updates/)).
- **External disk edits and browser tabs**: The [workspace window](https://hyperclaylocal.com/docs/guide/workspace/), [live documents](https://hyperclaylocal.com/docs/live-updates/), and the [Data API](https://hyperclaylocal.com/docs/data-api/) observe and merge changes on disk, and replacing an open live document saves unsaved live edits to `.hyperclay/recovered/`. However, a plain HTML page opened in a standalone browser tab without ClayJS live sync does not auto-reload when you edit the file in a text editor until you refresh the tab.
- **No local user accounts, permissions, or multi-tenant isolation**: Whoever can reach a folder's local port owns every file in that folder. Multi-user permissions, viewer access, and public hosting live on [Hyperclay](https://hyperclay.com/docs/).
- **Electron memory footprint**: Memory use of 100 to 200 MB is normal because Hyperclay Local is an Electron app.

## Sync and file limits

When syncing with hyperclay.com (see [What syncs](https://hyperclaylocal.com/docs/what-syncs/)):

- **Document upload size**: Documents (`.html` and `.htmlclay`) over 5 MiB on hyperclay.com are downloaded during initial setup, but documents larger than 5 MiB are not uploaded back to the server.
- **Attachment size**: Non-HTML files (attachments) larger than your hyperclay.com plan's per-file upload cap stay on your computer and do not sync until the file shrinks or your plan cap increases.
- **Folder depth**: Synced paths cannot exceed 5 folder levels deep.
- **File and folder naming**: File names are limited to 255 bytes and cannot use Windows reserved names. Folder names must use lowercase letters, numbers, hyphens, and underscores. Document names must be lowercase and end in `.html` or `.htmlclay`.
- **Skipped paths**: Dotfiles and dot-directories (`.hyperclay/`, `.trash/`, `.DS_Store`), `node_modules`, `sites-versions`, `tailwindcss`, `Thumbs.db`, `desktop.ini`, editor backup files (`*~` or `#...#`), and symlinks are never synced.
- **Locked `uploads/` folder**: The top-level `uploads/` folder in a synced root can never be deleted, renamed, or moved.
- **Team viewers**: If you are a viewer on a team rather than an editor, that team does not get a local folder or local port; viewers open team documents on hyperclay.com (see [Offline, paused and viewer states](https://hyperclaylocal.com/docs/sync-states/)).

## Live data, AI editing, and backup limits

- **Live-data values**: Live-data saves accept values up to 5 MB.
- **AI editing**: Runs one edit per document at a time, refuses selections larger than 900 KB, aborts after 5 minutes, and accepts at most 8 `@file` context files inside the served folder (up to 256 KB per file and 1 MB in total; see [AI editing](https://hyperclaylocal.com/docs/guide/ai-editing/)).
- **Backup retention**: Local backups in `.hyperclay/versions/` keep versions from the last 60 days plus the newest 20 versions per document. Recovered copies in `.hyperclay/recovered/` are never pruned (see [Recover from backups](https://hyperclaylocal.com/docs/guide/backups/)).