Hyperclay Local
  1. Hyperclay Local
  2. Docs
  3. Reference
  4. Rejected requests

Rejected requests

Why a local server or workspace request returns 403 Forbidden and how loopback, origin, and symlink checks work.

Every folder server in Hyperclay Local enforces origin-wide loopback, Origin, Fetch Metadata, and symlink checks. These rules apply across the entire origin, not per route, and are the usual reason a request that looks valid returns 403 Forbidden.

Loopback Host header#

The Host header must name a loopback address: localhost, any 127.x.x.x address, or ::1 in any valid IPv6 spelling. Any other Host value returns 403 with Invalid Host header.

Checking the Host header stops DNS rebinding attacks, which binding the socket to 127.0.0.1 alone does not prevent.

Cross-origin write protection#

On POST, PUT, PATCH, and DELETE requests:

  • Sec-Fetch-Site: cross-site is refused.
  • Origin: null is refused.
  • Any other Origin header must be a loopback origin on any port (http://localhost:<port>, http://127.x.x.x:<port>, or http://[::1]:<port>).
  • A request with no Origin header at all is allowed, which is why curl, local shell scripts, helper programs, and the sync engine work.

Refused write requests return 403 with a JSON error body:

JSON
{"msg":"Cross-origin requests are not allowed.","msgType":"error"}

Single-user cookies on local ports#

Every request to a served folder sets isAdminOfCurrentResource=true and isLoggedIn=true cookies. Each local folder server is single-user by design: whoever can reach the folder’s port (4321 for your personal folder, or a team folder’s local port; see Folders and ports) owns every file in that folder. There is no user authentication on local folder routes.

The workspace window shell server applies an additional per-launch token (X-Workspace-Token) alongside Host, Origin, and Fetch Metadata checks on its internal API routes. When you open http://localhost:<port>/ in a browser, the server redirects through /enter?ticket=... using a one-time ticket that expires after 60 seconds; an unknown or expired ticket returns 403 Forbidden, while a valid ticket sets an HttpOnly, SameSite=Lax cookie named hyperclay-workspace-<port> for 24 hours.

Symlinks pointing outside the served folder are consented at open time only:

  • A symlink created while the server is running is refused on both reads and writes.
  • /_/uploads/ serves only files inside the real uploads/ folder, so a symlink pointing outside uploads/ reaches nothing (see Metadata and uploads).
  • @file context in AI editing follows symlinks only when the target stays inside the served folder, and refuses hidden files and folders both by name and after resolving symlinks.