# Addresses and reserved routes

> How Hyperclay Local maps URLs on localhost to documents, static files, client-side routes, and reserved /_/ endpoints.

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

Every served folder in Hyperclay Local runs an HTTP server bound to `127.0.0.1` (`localhost`) on its assigned port: `4321` for your personal folder, and `5432`, `6543`, `7654`, `8765`, `9876` (or a random port between `49152` and `65535`) for [team folders](https://hyperclaylocal.com/docs/guide/team-folders/). See [Folders and ports](https://hyperclaylocal.com/docs/folders-and-ports/).

## URL mapping

With the server running on a folder (shown below using port `4321`):

| URL | Serves |
|---|---|
| `http://localhost:4321/` | On a top-level browser `GET`, redirects (`302`) to the [workspace window](https://hyperclaylocal.com/docs/guide/workspace/) entry URL (`/enter?ticket=…`, valid for 60 seconds, which sets a `hyperclay-workspace-<port>` session cookie). For `HEAD` requests, framed loads, or when the workspace cannot start, serves the directory listing of the folder root. |
| `http://localhost:4321/notes.html` | The document `notes.html` |
| `http://localhost:4321/blog/` | Directory listing of `blog/` |
| `http://localhost:4321/blog/post.html` | The document `blog/post.html` |
| `http://localhost:4321/blog/post.html/any/route` | Also `blog/post.html`; everything after the `.html` or `.htmlclay` extension is a client-side route |
| `http://localhost:4321/logo.png` | Any static file, sent as-is |
| `http://localhost:4321/_/uploads/assets-notes/photo-2cf24d.png` | An attachment stored inside `uploads/` in the served folder |

## Documents and static files

- **Documents**: Files ending in `.html` and `.htmlclay` are served as malleable documents. Each served document carries a `documentetag` attribute on its root `<html>` element with the ETag stamp of the served bytes (the file on disk is untouched, and the attribute is stripped on save).
- **Static assets**: Every other file type is served as a static asset with `X-Content-Type-Options: nosniff`.
- **SVG and uploaded web-page types**: `.svg` and `.svgz` files, as well as any web-page file type placed inside `uploads/`, are served with `Content-Disposition: attachment` and `X-Content-Type-Options: nosniff`. An SVG or uploaded HTML file cannot execute inline with the origin's authority.
- **Uploads route (`/_/uploads/`)**: Serves only files inside the real `uploads/` folder of the served root. Every byte of a filename outside the unreserved set is percent-encoded, and symbolic links pointing outside the folder are refused.

## Path validation and hidden files

Requests are validated before they touch the filesystem:

- No backslashes (`\`), no null bytes (`\0`), no absolute paths, and no `.` or `..` segments.
- No path segment longer than `255` characters.
- Any path segment beginning with `.` (including `.hyperclay/`, `.hyperclay/versions/`, `.hyperclay/conflicts/`, and `.trash/`) returns `404`.
- `sites-versions` is a reserved first path segment and is never served over HTTP.

See [Rejected requests](https://hyperclaylocal.com/docs/rejected/) for the complete list of request checks.

## Reserved `/_/` system routes

All system endpoints live under the `/_/` prefix:

- `/_/save` (and legacy `/save`): Write a document to disk. See [Saving and stale-write protection](https://hyperclaylocal.com/docs/saving/).
- `/_/meta`: Inspect host capabilities and per-document metadata. See [Metadata and uploads](https://hyperclaylocal.com/docs/metadata-and-uploads/).
- `/_/upload` and `/_/uploads/`: Upload and serve document attachments. See [Metadata and uploads](https://hyperclaylocal.com/docs/metadata-and-uploads/).
- `/_/sync` and `/_/live-sync`: Broadcast and subscribe to live tab updates. See [Live updates between tabs](https://hyperclaylocal.com/docs/live-updates/).
- `/_/api`: Read and write documents as JSON using CSS selector rules. See [Data API](https://hyperclaylocal.com/docs/data-api/).
- `/_/data-loss`: Inspect or resolve data-clobber guard incidents. See [Saving and stale-write protection](https://hyperclaylocal.com/docs/saving/).
- `/_/versions`, `/_/version`, and `/_/restore`: List, inspect, and restore saved versions and recovered copies. See [Version history routes](https://hyperclaylocal.com/docs/version-history/).
- `/_/wire`: Run helper programs and wire commands. See [Programs and helpers](https://hyperclaylocal.com/docs/programs/).

Any unknown path under `/_/` returns `404`, so a request such as `/_/foo.html` never falls through to be served as a document.