# Hyperclay docs, every page > The hosted platform for malleable HTML documents: your workspace, sharing, teams, custom domains and the APIs around them. # Hyperclay docs > Keep, edit, share, and publish HTML files that save themselves in your workspace on Hyperclay. Source: https://hyperclay.com/docs/ Hyperclay is the hosted platform at hyperclay.com for keeping, editing, sharing, and publishing HTML files in a workspace. With the ClayJS script, a file edits itself in the browser and saves changes back into itself. Hyperclay gives you teams, share links, subdomains and custom domains, version history, and hosted AI. ## What do you want to do? - **Share a malleable document with your team**: Keep documents in a workspace, send share links, and publish on the web with Hyperclay. Start with the [Quick start](https://hyperclay.com/docs/guide/quick-start/). - **Use a document on your own computer**: Open `.htmlclay` files on your computer that save back to disk with [HTML Clay](https://htmlclay.com/docs/), a free, open-source desktop app. - **Sync a folder between your computer and Hyperclay**: Serve a folder of malleable documents on your computer and sync it both ways with your workspace using [Hyperclay Local](https://hyperclaylocal.com/docs/). - **Make your own malleable document**: Build self-saving HTML files with one script tag using [ClayJS](https://clayjs.com/docs/), the free, open-source browser library. ## Why Hyperclay exists Reusable, portable software that anyone can use and improve on their own needs a lightweight visual and data format. The HTML file fits that job because it holds the interface, code, and data in one place and gives you the full web platform. We built a system around the HTML file so you can update a document like a web application, on the web or on your computer. Each document stays a portable file you can download or email around. Hyperclay hosts those files so you can open them in any browser, keep version history, and work with a team. ## What people do with Hyperclay - **Keep a daily work journal**: Track client work, to-dos, finished tasks, and project plans in one document. - **Run project dashboards**: Have an AI agent build a multi-week project dashboard and update it through the document's JSON API. - **Collect answers and screenshot feedback**: Use a form where an AI agent asks questions, or mark up screenshots with a built-in feedback tool so the AI reads your notes from the HTML. - **Share diagrams and tools**: Collaborate in [teams](https://hyperclay.com/docs/teams/), send [share links](https://hyperclay.com/docs/share-links/), publish on custom domains, or edit with [hosted AI](https://hyperclay.com/docs/hosted-ai/). Every file stays under your control. ## Where to go next - [Quick start](https://hyperclay.com/docs/guide/quick-start/): Sign up, start a document from a template, edit it, and open its live address. - [Your workspace](https://hyperclay.com/docs/guide/workspace/): Navigate your files, code editor, and version history side by side. - [Making malleable documents](https://hyperclay.com/docs/making-malleable-documents/): Learn how ClayJS works and how to bring HTML files into Hyperclay. - [Work on your computer](https://hyperclay.com/docs/guide/your-computer/): Sync folders with Hyperclay Local or open standalone files with HTML Clay. --- # Quick start > Sign up for Hyperclay, start a document from the template gallery, edit it in your workspace, and open its live address. Source: https://hyperclay.com/docs/guide/quick-start/ You can publish an editable document on the web in a few minutes without setting up a local build environment. This guide walks through signing up, starting a document from the gallery, editing it, watching it save, and opening its public address. ## Create and publish your first document 1. **Sign up for an account.** Start at [Free signup](https://hyperclay.com/free-signup), enter your email address, and open the signup link it sends you. Choose your username and password on the welcome page. A free account holds up to 10 documents. Your username gives you an address namespace at `https://.hyperclay.com`. 2. **Choose a template.** Open the [template gallery](https://hyperclay.com/templates) and copy a template into your account. A free account starts with a template and edits it in place. 3. **Open your document.** Find the copy in your workspace and open it. With an active Personal or Maker plan, you can also use **New document** to create a blank document and edit its source in the code editor. 4. **Edit your document and watch it save.** Your document opens in view inside the workspace beside your files, the way a visitor sees it. Open the document menu and click **Return to editing** (or click **Edit** on the page, or press `⌘⇧E`), then click into the page and change some text or add a heading. (If you started an **Untitled** **Document**, it renames itself once to match the first heading you type.) While your change writes to the server, the workspace status shows **Saving…** and clears when the save finishes. Every save in the browser records a snapshot in the document's **Versions** panel. 5. **Switch between view and edit.** Open the document menu and click **View as visitor** to see the page without editing controls, as a visitor sees it, and **Return to editing** to go back. A document you create with **New document** in the workspace opens straight in edit mode. 6. **Open its live address.** Open the document menu and click **Open in its own tab** (`⌘⇧O`), or check the **Address** row in the document's **Info** dialog. Public documents are served at `https://.hyperclay.com/.html`. Open that address in a private or incognito browser window to see the live, read-only view. > [!NOTE] > The **Journal** template carries a **Starts private** tag and is created as a private document. Only you and people you grant access can open a private document until you open its actions menu and choose **Make public**. ## Where to go next - Explore the workspace file tree, code editor, and version history in [Your workspace](https://hyperclay.com/docs/guide/workspace/). - Build from a **Blank** template with [ClayJS](https://clayjs.com/docs/guide/quick-start/) or import an existing HTML file in [Make your own document](https://hyperclay.com/docs/making-malleable-documents/). - Claim a custom `.hyperclay.com` subdomain or connect your own domain in [Addresses and subdomains](https://hyperclay.com/docs/addresses/) and [Publish on your own domain](https://hyperclay.com/docs/guide/domains/). --- # Your workspace > Tour the Hyperclay workspace: your sidebar, files and folders, open documents with code and versions alongside, Recent, pins, search, and Trash. Source: https://hyperclay.com/docs/guide/workspace/ The Hyperclay dashboard is a workspace where you keep, find, and edit your malleable documents. Your file tree stays in a sidebar on the left while documents open beside your files, with their code and version history alongside. ## The sidebar The left sidebar holds your navigation and your file tree. At the top sit **Filter files**, **Recent**, **Inbox**, **Shared with me**, **Home**, and any documents you have added under **Pinned**. From the **New** menu, you can start a document from [Templates](https://hyperclay.com/docs/templates/), create a folder, import existing pages, or upload files from your computer. ## Files and folders Click **Home** to view your workspace in the files table, or browse your folders directly in the sidebar tree. You can nest folders up to five levels deep, rename or move items in a single step, and select up to 100 rows at once to move or delete them in bulk; see [Files and folders](https://hyperclay.com/docs/files/). When a document uploads images or other attachments, they are stored in a dedicated subfolder inside `uploads` and keep working even when you move the document; see [Uploads](https://hyperclay.com/docs/uploads/). ## Open a document beside your files Clicking any document in the sidebar or files table opens it right in the workspace beside your files, so you can move between documents without leaving the dashboard. A document opens in view, the way a visitor sees it; to change it, open the document menu and choose **Return to editing** (or click **Edit** on the page, or press `⌘⇧E`). A document you have just created from a template opens in edit mode. Along the top of the open document, tabs for **Code**, **Versions**, **Domains**, and **Comments** let you edit the document's HTML in the [Code editor](https://hyperclay.com/docs/code-editor/) or browse and restore earlier snapshots in [Version history](https://hyperclay.com/docs/version-history/). You can also click any uploaded image, PDF, or text file to preview it in place, and open the **Code** tab on a text upload to edit and save it directly. ## Recent and pins Click **Recent** in the sidebar to see the last 50 documents you opened, grouped by day under **Today**, **Yesterday**, and **Earlier**. To keep an important document at the top of the sidebar, open its menu and choose **Pin to sidebar** so it stays listed under **Pinned** above your folder tree. For details on both lists, see [Search, Recent and pins](https://hyperclay.com/docs/search/). ## Search Click **Filter files** in the sidebar or press Cmd+K (Ctrl+K on Windows and Linux) to search your workspace. Typing filters the sidebar tree by file name right away, and once you type two or more characters, **Found inside documents** lists documents whose text contains your words. Clicking a content result opens the document beside your files and highlights the matched word on the page; see [Search, Recent and pins](https://hyperclay.com/docs/search/). ## Trash Deleting a document, upload, or folder moves it to **Trash** instead of erasing it right away. Open **Account menu** and choose **Trash** to restore deleted items to their original folder within 30 days, or delete them permanently; see [Trash](https://hyperclay.com/docs/trash/). --- # Making malleable documents > Hyperclay runs malleable documents built with ClayJS. What ClayJS does, where to learn it, and how to bring your own file into Hyperclay. Source: https://hyperclay.com/docs/making-malleable-documents/ You make malleable documents with [ClayJS](https://clayjs.com/docs/), and the ClayJS docs are the place to learn it. This site covers the Hyperclay hosted platform, not how to build documents from scratch. When you want to build your own malleable document, go to the ClayJS docs. ## What ClayJS does ClayJS is the free, open-source browser library that turns one HTML file into a malleable document. Every malleable document is built with it. - **One script tag**: Add a single script tag to an HTML page with no build step. - **Edits in place and saves to its host**: Make elements editable, persist form controls and DOM state, strip temporary editing controls on save, and write the updated HTML back to its host. - **Live sync**: Merge changes in real time across open browser tabs and people. - **Plugins**: Load plugins such as the schema-driven CMS, rich-text editing with `richclay`, sortable lists, undo, uploads, and AI editing. - **Works anywhere**: Run the same file on Hyperclay, [HTML Clay](https://htmlclay.com/docs/), [Hyperclay Local](https://hyperclaylocal.com/docs/), or your own server. ## Learn ClayJS - [ClayJS docs](https://clayjs.com/docs/): Read the complete guide and API reference for building with ClayJS. - [ClayJS quick start](https://clayjs.com/docs/guide/quick-start/): Turn an HTML file into a self-saving document in a few minutes. - [A document explained line by line](https://clayjs.com/docs/guide/walkthrough/): See a complete ClayJS document explained line by line. ## Import an HTML file If you already wrote a malleable document on your computer, or if you have static `.html`, `.htm`, or `.htmlclay` pages (or a `.zip` archive of pages such as a Notion or Google Docs export), you can import them into your workspace as documents: 1. Open the folder in your workspace where you want the document to live. 2. Click **New** and choose **Import files…**. 3. In the **Import files** dialog, click **Choose files…** and select one or more `.html`, `.htm`, `.htmlclay`, or `.zip` files. Each imported HTML page becomes a document in the current folder. File names are lowercased and normalized to end in `.html` or `.htmlclay`, with `-2`, `-3`, and so on added if the name is already taken in that folder. Each page can be up to 5 MB. Any non-HTML files inside a `.zip` archive are added to your [uploads](https://hyperclay.com/docs/uploads/). See [Import and export](https://hyperclay.com/docs/import-export/) for full details. > [!NOTE] > At the bottom of the **Start a new document** gallery, the **Have a file already?** strip (**Choose a file**) opens the **Upload files** dialog, which stores the file as a static [upload](https://hyperclay.com/docs/uploads/) rather than importing it as a document. Use **New** and then **Import files…** when you want an HTML file to become an editable document. ## Use Make malleable on a static page If you imported a static HTML page that does not include ClayJS yet, you can add ClayJS to it from its actions menu: 1. Open the `…` actions menu on the document row in your file list, or open the document's `…` menu in the workspace editor. 2. Click **Make malleable**. 3. In the **Make malleable** dialog, click **Make malleable** to confirm. Hyperclay saves a backup of your current file first, then splices two script tags right before the closing `` tag without reformatting the rest of your file: - `https://clayjs.com/v1/clay.js` (with `?plugins=cms,sortable,undo,ai-edit` added automatically if the page already carries [CMS](https://clayjs.com/docs/plugins/cms/) rules) - `https://clayjs.com/v1/clay-ui.js` Once the workflow finishes, the page can save changes to itself and the **Make malleable** item disappears from the menu. The page opens in view mode, as every ClayJS document does. Press Cmd+Shift+E (Ctrl+Shift+E on Windows and Linux) to switch to editing, or load the [menu plugin](https://clayjs.com/docs/plugins/menu/) to give the page an **Edit** switch. **Make malleable** adds the ClayJS runtime and saving support, but it does not decide which elements on your page are editable. To make specific headings, paragraphs, or lists editable, either add ClayJS attributes yourself in the [code editor](https://hyperclay.com/docs/code-editor/) (see [ClayJS attributes](https://clayjs.com/docs/attributes/) and [CMS](https://clayjs.com/docs/plugins/cms/)) or use AI to wire up editable fields (see [Use AI](https://hyperclay.com/docs/guide/ai/)). ### Requirements for Make malleable - You must have code-editing permission on the document (the document owner or a team editor on an active paid plan). - The page must have a `` tag. Pages that use `` without a `` must be converted to a standard HTML page in the [code editor](https://hyperclay.com/docs/code-editor/) first. - The page must not already load ClayJS or load multiple copies of the library. - The page cannot be managed by a [collection](https://hyperclay.com/docs/collections/). --- # Versions and recovery > How Hyperclay protects your work with version history, a 30-day Trash, and full workspace zip exports. Source: https://hyperclay.com/docs/guide/versions/ Hyperclay gives you three ways to recover from mistakes and keep copies of your work: version history on every document, a 30-day Trash for deleted files and folders, and zip exports you can store on your own computer. ## Roll back edits with version history As you and your collaborators edit a document, Hyperclay records snapshots in the document's **Versions** tab. You can browse the latest 50 versions, click **View** to inspect an earlier snapshot, or click **Restore** to replace the current document with that version. Restoring a version always saves a backup of the current document first, so rolling back never costs you the state you had right before the restore. See [Version history](https://hyperclay.com/docs/version-history/). ## Recover deleted items from Trash Deleting a document, uploaded file, or folder moves it to **Trash** rather than erasing it immediately. When you delete a folder, the folder and everything inside it stay together in **Trash** as one recoverable unit. Deleted items and their version history remain in **Trash** for 30 days. Account owners and team editors can open **Account menu**, choose **Trash**, and click **Restore** to return an item to its original folder. See [Trash](https://hyperclay.com/docs/trash/). ## Keep your own copies with export Every malleable document is a standard HTML file that you can keep outside Hyperclay: - To save a copy of one document, open its **Actions for** menu and click **Download** to download the `.htmlclay` file. - To back up everything you own at once, open **Account menu** and click **Export workspace** to download a single `.zip` containing every folder, document, and uploaded file in your workspace. See [Import and export](https://hyperclay.com/docs/import-export/) for full details on downloading and re-importing your files. ## Unsaved writing kept in your browser The Journal, Kanban and Block editor templates also keep a copy of writing that has not saved yet, in your browser. If a tab closes or the connection drops before a save lands, the document offers that writing back the next time you open it in edit mode, and you choose whether to keep it. This copy lives only in that browser and is not a version. See [Recovery](https://clayjs.com/docs/recovery/). --- # Share and collaborate > Choose how to share a document on Hyperclay: share links, named viewers and editors, teams, live presence, and comments. Source: https://hyperclay.com/docs/guide/sharing/ Hyperclay gives you three ways to let other people view or edit a document, plus live presence and comments once they are inside. | Way to share | What it is | Who it suits | |---|---|---| | **[A share link](https://hyperclay.com/docs/share-links/)** | A URL that opens one document to view or to edit | Anyone, including people without a Hyperclay account | | **[Sharing with a person](https://hyperclay.com/docs/share-with-a-person/)** | One named person gets viewer or editor access to one document | Someone outside your team who works with you on one document | | **[A team](https://hyperclay.com/docs/teams/)** | A shared workspace with its own subdomain and its own document library | People you work with regularly across many documents | ## Share links Each document can have a **View link** and an **Edit link** that work even when the document is private. Anyone holding the link can open the document in their browser without signing in or creating an account, and you can copy the link, show its QR code, or revoke it at any time. An edit link opens the document in view like any other link, and the person turns on editing with the page's **Edit** switch or `⌘⇧E`. See [Share links](https://hyperclay.com/docs/share-links/). ## Share with a person When you want to grant access to a specific person by email rather than a link anyone can forward, open **Share…** on a document and invite them under **People** as a viewer or an editor. Documents other people share with you by name appear in the **Shared with me** tab on your dashboard, without exposing the folder they live in. See [Share with a person](https://hyperclay.com/docs/share-with-a-person/) and [Shared with me](https://hyperclay.com/docs/shared-with-me/). ## Teams A team is a shared account with its own address (such as `acme.hyperclay.com`), its own documents and folders, and its own trash. You sign in as yourself and work in the team workspace as an **Owner**, **Editor**, or **Viewer**, with every save attributed to the person who made it. See [Teams](https://hyperclay.com/docs/teams/). ## Presence and comments When more than one person has the same document open, an avatar row in the top bar shows who is viewing or editing right now. Anyone with a confirmed email address who can open the document can also pin comments to a spot on the page or to the whole document, mention collaborators with `@`, and follow replies in the workspace **Inbox**. See [Presence and comments](https://hyperclay.com/docs/presence-and-comments/). --- # Publish on your own domain > Give a document a dedicated Hyperclay subdomain, then connect your own custom domain with automatic TLS. Source: https://hyperclay.com/docs/guide/domains/ Every document you create in Hyperclay starts with an address under your account namespace, such as `.hyperclay.com/.html`. When you are ready to publish a document at its own root address, you can promote it to a dedicated `.hyperclay.com` subdomain first, and connect a custom domain you own whenever you want. Both options are included on the [Personal and Maker plans](https://hyperclay.com/docs/billing/). ## Step 1: Claim a Hyperclay subdomain A Hyperclay subdomain gives your document a short address like `my-project.hyperclay.com` without buying a domain or editing DNS records. 1. Open the document's menu and choose **Domains** (or open its **Domains** tab). 2. In the **Current address** row, click **Change**. 3. In the **Hyperclay subdomain** field, type the subdomain name you want before `.hyperclay.com`. Names use lowercase letters, numbers, hyphens, and underscores. 4. Click **Claim subdomain** (or **Change subdomain** if the document already has one). Your document is immediately live at `https://.hyperclay.com`. Changing an existing subdomain updates the document's public address, so links using an earlier claimed subdomain stop working. Personal plans start with 3 subdomains (growing by 1 each month up to 10), and Maker plans start with 6 (growing by 2 each month up to 25). For naming rules and how folder paths and addresses fit together, see [Addresses and subdomains](https://hyperclay.com/docs/addresses/). ## Step 2: Connect your own domain When you have a domain of your own at a DNS provider or registrar, connect it in the same **Domains** panel. **Step 1: Add the domain in Hyperclay** In the document's **Domains** panel, under **Custom domains**, click **Add domain**. Enter a bare domain such as `example.com` or a subdomain such as `app.example.com`. If you enter a bare domain, leave **Also send `www.` here** checked so `www.` redirects to the bare domain, then click **Add domain**. **Step 2: Create the DNS records at your provider** Look at the **DNS setup** table on the **Domains** page and copy each record into your DNS provider: - A **Traffic** record: an `A` record pointing to `5.161.29.91` for a bare domain, or a `CNAME` record pointing to `domains.hyperclay.com` for a subdomain. - A **Validation** record: a `CNAME` record for `_acme-challenge.` pointing to the validation target shown in the table. Keep this record in place permanently so TLS certificates can renew. If you checked **Also send `www.` here**, add the `www` records listed in the table as well. **Step 3: Check that the domain is live** After saving your DNS records, return to the **Domains** panel and click **Refresh status**. Once DNS propagation finishes and the certificate is provisioned, **Status** changes to **Active** and **TLS** changes to **Issued**. For wildcard domains, Cloudflare settings, status meanings, and removing a domain, see [Custom domains](https://hyperclay.com/docs/custom-domains/). --- # Work on your computer > Edit and run malleable documents on your computer using Hyperclay Local for two-way folder sync or HTML Clay for standalone local files. Source: https://hyperclay.com/docs/guide/your-computer/ Every malleable document is a standard `.html` or `.htmlclay` file that you own. If you open a downloaded document directly in a web browser from a `file://` path, the page renders in view mode, but the browser cannot write changes back to your disk on its own. To edit and save malleable documents on your computer (macOS, Windows, or Linux), use one of two free desktop apps: **[Hyperclay Local](https://hyperclaylocal.com/docs/)** or **[HTML Clay](https://htmlclay.com/docs/)**. ## When to pick which - **Pick [Hyperclay Local](https://hyperclaylocal.com/docs/)** when you want to work on a folder of documents and uploads in a local workspace window, edit files in your own desktop code editor, or sync folders in both directions with your personal and team workspaces on hyperclay.com. - **Pick [HTML Clay](https://htmlclay.com/docs/)** when you want to double-click and edit individual `.htmlclay` files anywhere on your disk, completely offline and without connecting an account. ## Sync folders with Hyperclay Local [Hyperclay Local](https://hyperclaylocal.com/docs/) runs a local server for a folder on your computer and opens your files in the same workspace interface as Hyperclay's dashboard. You can run Hyperclay Local offline for free, or connect it to your Hyperclay account with a sync key: - **Two-way live sync**: Edits, new documents, uploads, nested folders, renames, moves, and deletions sync in real time between your computer and hyperclay.com. - **Team folders**: One sync key syncs your personal workspace and creates a separate local folder for each [team](https://hyperclay.com/docs/teams/) where you are an owner or editor. - **Offline reconciliation and conflict resolution**: When you work offline, Hyperclay Local keeps automatic local backups of every save and reconciles your changes when you reconnect. If a file changed on both sides, sync shows the conflict and lets you pick which version to keep. - **Use your own tools**: Because your documents sit in a normal folder on disk (with `.html` or `.htmlclay` extensions), you can edit them in any desktop code editor or let local scripts and AI agents work on them. ### Connect Hyperclay Local to your account 1. In Hyperclay, open the **My account** menu and click **Generate sync key…**. 2. In the **Generate sync key** dialog, generate a new key and click **Copy key**. Keep the key private; it is shown only once when created and expires after one year. (Generating a sync key requires an active paid plan, or an editor role on a team with a **Maker** plan.) 3. Follow the [Hyperclay Local quick start](https://hyperclaylocal.com/docs/guide/quick-start/) and [Sync with hyperclay.com](https://hyperclaylocal.com/docs/guide/sync/) to install the app and paste your sync key. ## Open single files with HTML Clay [HTML Clay](https://htmlclay.com/docs/) is a desktop app for opening, editing, and saving standalone `.htmlclay` documents on macOS, Windows, and Linux. - **Double-click to open**: Open any `.htmlclay` file from Finder or File Explorer like a regular document. Plain `.html` files can also be opened read-only with their stylesheets, scripts, and images. - **Local version history**: Every save writes back to the file on disk and records a local version you can browse and restore. - **Self-contained assets and Tailwind**: Upload files into a folder beside the document, build Tailwind CSS locally from a single link tag with no build step, and export a document and its attachments as a portable zip. To get started with standalone local files, read the [HTML Clay quick start](https://htmlclay.com/docs/guide/quick-start/). To download documents from your Hyperclay workspace to open on your computer, see [Import and export](https://hyperclay.com/docs/import-export/). --- # Use AI > Build new documents with Describe anything, edit open pages with AI edit, or connect your own coding agent through the Sync API. Source: https://hyperclay.com/docs/guide/ai/ Because every Hyperclay document is a single HTML file that holds its own markup, styles, behavior, and data, AI tools can build or edit an entire document in one place. You can use AI with Hyperclay in three ways: 1. **[Describe anything](https://hyperclay.com/docs/hosted-ai/#describe-anything)**: Write a brief in the dashboard and let Hyperclay build a complete document from scratch. 2. **[AI edit](https://hyperclay.com/docs/hosted-ai/#ai-edit)**: Switch the document to edit (click **Edit**, press `Cmd+Shift+E`, or choose **Return to editing** in the workspace's document menu), then press `Cmd+J` to ask Hyperclay's hosted AI to change the page in place. 3. **[Your own AI agent](https://hyperclay.com/docs/agents/)**: Make an agent key and connect Claude Code, Claude Desktop or Cursor to read and edit your documents. ## Build a document with Describe anything When you want a custom tool, tracker, or page built from scratch, open **New** in your workspace, choose **New document**, and pick **Describe anything**. Write a description of at least 200 words (around 500 is better) explaining who will use the document and how it should work, then click **Build · up to 350 credits**. Hyperclay builds the document in about 5 to 10 minutes and saves it into your workspace. Failed builds do not use any credits. See [Hosted AI](https://hyperclay.com/docs/hosted-ai/#describe-anything) for credit pools and plan requirements. ## Edit an open document with AI edit When you are editing a hosted document that includes the ClayJS [ai-edit](https://clayjs.com/docs/plugins/ai-edit/) plugin, press `Cmd+J` (`Ctrl+J` on Windows and Linux) to open the prompt bar. Documents open in view, so switch to edit first: click **Edit** on the page, press `Cmd+Shift+E`, or choose **Return to editing** in the workspace's document menu. Describe the change you want, such as adding a filter bar, restyling a section, or wiring up a new field, and send it. The document's owner and [team editors](https://hyperclay.com/docs/teams/) can run AI edits on any workspace covered by a Personal or Maker plan. Edits stream into the page as they happen and draw from the account owner's monthly AI credit pool. If you have a static HTML page and want to make its content editable with the [ClayJS CMS plugin](https://clayjs.com/docs/plugins/cms/), you can also open the document's three-dot menu in the dashboard and choose **Add CMS with AI** (or **Regenerate CMS with AI**). Hyperclay proposes the content structure, validates it, and applies the CMS rules and attributes in the background. Always review the resulting fields on the page before handing it over. For full details on hosted AI features, credits, and limits, see [Hosted AI](https://hyperclay.com/docs/hosted-ai/). ## Work on your files with your own agent If you use a coding agent that can run shell commands, such as Claude Code or Codex, it can work on your Hyperclay documents directly over HTTP with `curl` and `jq` (or on local files synced with [Hyperclay Local](https://hyperclaylocal.com/docs/guide/ai-editing/)). To connect Claude Code, Claude Desktop or Cursor through an MCP server instead, with a key you can limit to a team or folder, see [Edit with AI agents](https://hyperclay.com/docs/agents/). The rest of this section is for scripts that use `curl`. Suppose you ask your coding agent to mark `"Renew passport"` as done in `tasks.html`. It runs a few `curl` commands, updates the document on `hyperclay.com` so the item reads `done`, and everyone who loads the page sees the change. An agent reaches your documents in two ways: - **Read public data as JSON without a key**: Any public document that includes an `api` rules tag exposes its structured data as JSON at `/_/api/.html` (and any document can be queried with `?data=`). See [Page data endpoints](https://hyperclay.com/docs/page-data/) and [data: pages as JSON](https://clayjs.com/docs/plugins/data/). - **Read and write full HTML with a sync key**: With an `hcsk_` sync key generated from your account menu (**Generate sync key…**), an agent can list your documents, read private documents, fetch a document's whole HTML, edit it locally, and save it back through the [Sync API](https://hyperclay.com/docs/sync-api/). Give an agent a sync key only when it needs one, and revoke the key when the job is done. For example, a public document at `https://alice.hyperclay.com/tasks.html` can expose its tasks to an agent with an `api` rules tag in its body: ```html
  • Renew passport open
  • Book flights done
``` Generating a sync key requires a Personal or Maker plan on your own account, or an owner or editor role on a team whose owner is on Maker. See [Sync API for agents and scripts](https://hyperclay.com/docs/sync-api/) for the step-by-step `curl` commands to list, read, update, undo, and revoke access. --- # Files and folders > Create, name, rename, move, and bulk-manage documents and folders up to five levels deep in your workspace. Source: https://hyperclay.com/docs/files/ You organize your documents and uploaded files in folders inside your workspace. You can nest folders up to five levels deep, rename or move items individually, or select up to 100 items at once in the files table to move or delete them together. ## Name rules When you type a document or folder name in a create or rename dialog, Hyperclay formats it as you type: - Uppercase letters are converted to lowercase. - Characters outside lowercase letters (`a` to `z`), numbers (`0` to `9`), hyphens (`-`), and underscores (`_`) are replaced with hyphens. - Consecutive hyphens collapse into a single hyphen, and leading or trailing hyphens are trimmed. - Document names must end in `.html` or `.htmlclay`. If you omit the extension, `.html` is added automatically. Folder names do not take an extension. When the dialog adjusts what you typed, it shows **Saved as** followed by the formatted name below the field. If the resulting name is invalid, the dialog displays the reason and disables the submit button: - A name cannot be empty or longer than 255 characters. - A name cannot start or end with a hyphen, or contain consecutive hyphens. - A single underscore (`_`) and system names such as `con` are reserved. Uploaded files keep their original names instead of being slugged. Upload names can be up to 255 bytes and may contain letters, numbers, spaces, and `._()[]{}-!@#$%^&+=`, but cannot contain `/ \ < > : " | ? *` or reserved system names. ## Folder depth Folders can nest up to 5 levels below the root of your workspace: - Creating a sixth folder level is refused with **Maximum folder depth reached (5 levels)**. - Moving a folder to a destination where it or its subfolders would pass 5 levels is refused with **Moving would exceed maximum folder depth (5 levels)**. - You cannot move a folder into itself or into any of its own subfolders. The top-level `uploads` folder holds attachments for your documents and is locked: it cannot be renamed, moved, or deleted. See [Uploads](https://hyperclay.com/docs/uploads/). ## Create a document or folder To create a folder: 1. Open the **New** menu and start the **Create folder** dialog. 2. Enter a name in **Folder name**. 3. Click **Create folder**. To create a document, open **New** and click **New document** to pick a starter in the gallery; see [Templates](https://hyperclay.com/docs/templates/). To copy an existing document, open its **Actions for** row menu and click **Duplicate**. The default name is `-copy.html`, trimmed if needed to stay within 255 characters. ## Rename a document or folder Account owners and team editors can rename any document, upload, or normal folder (team viewers cannot rename items). A file a document uploaded, and that document's own folder inside `uploads`, cannot be renamed or moved by themselves: they move and rename with their document. 1. In the files table, open the item's **Actions for** menu and choose **Rename** (or rename the item inline in the sidebar file tree). 2. Enter the new name in the **Name** field. 3. Click **Rename**. ## Move a document or folder Account owners and team editors can move items between folders: 1. Open the item's **Actions for** menu and click **Move to folder…**. 2. In the **Move** dialog, choose a destination folder (pick **Files** to move the item to the root of your workspace). 3. Click **Move**. Moving and renaming happen in a single atomic operation, so a move either finishes completely or leaves the item untouched. > [!WARNING] > Moving an item changes its path-based URL, including the paths of everything inside a moved folder. Update any links that point to the old path. Pictures and files a document uploads are stored in its own `uploads/assets-document-/` folder, named after the document's id, so they keep working when the document is renamed or moved. ## Bulk select In the files table, use the row checkboxes to act on multiple items at once. Only rows you have permission to move or delete can be selected. - Click individual checkboxes to add or remove rows, or Shift-click a checkbox to select a range of rows. - Click the header checkbox (**Select all**, or **Select loaded items** when more rows remain) or press Cmd+A (Ctrl+A on Windows and Linux) to select all loaded rows. - Press Escape or click **Clear selection** in the floating bar to clear your selection. Switching folders also clears the selection. When one or more rows are selected, a floating bar shows **`` selected** and offers two actions: **Move to folder** and **Delete**. Bulk operations process 1 to 100 items per request, and larger selections are split into batches of 100 automatically. ### Move to folder Click **Move to folder** in the floating bar to open the **Move `` items** dialog. Pick a destination folder and click **Move here**. Moving a folder moves everything inside it and updates path-based URLs for all moved items. ### Delete Click **Delete** in the floating bar to open the **Delete `` items?** confirmation dialog, then click **Delete `` items**. Every selected item moves to [Trash](https://hyperclay.com/docs/trash/), and any selected folder includes everything inside it. When a bulk move or delete finishes, a notification reports **Moved `` items.** or **Deleted `` items.** If any items could not be changed, the notice reports **`` items did not change.** with the reason for each file and a **Retry failed or unattempted** button. --- # Search, Recent and pins > Search file names and words inside your documents, reopen recent work grouped by day, and pin up to 50 documents to the sidebar. Source: https://hyperclay.com/docs/search/ You can find any document in your workspace from the left sidebar: search file names and the words inside your documents, reopen documents you worked on recently, or pin up to 50 documents to keep them at the top of the sidebar. ## Search The workspace sidebar has a **Filter files** box at the top. Press Cmd+K (Ctrl+K on Windows and Linux) from anywhere in the workspace to jump straight to it. On a phone, the shortcut opens the sidebar first. ### Filter by file name As you type in **Filter files**, the sidebar file tree narrows immediately to items whose file names match what you typed, hiding rows that do not match. When no file names match your query, the tree displays **No file names match.** ### Search inside documents Once you type 2 or more characters, a second section headed **Found inside documents** appears below the file tree. It searches the text inside your own active documents and documents shared with you, skipping anything in [Trash](https://hyperclay.com/docs/trash/). - Search uses up to 6 words, with up to 32 characters per word, and returns up to 20 matching documents. - Each result shows the document's name and where it lives: its folder name, **Files** if it sits at the root of your workspace, or **Shared by ``** if someone else owns it. - Below the name, a snippet of up to 24 words shows the matching passage with your search words highlighted. - If no document text matches, the section shows **No document mentions "``".** ### Highlighting in the open document Click any result under **Found inside documents**, or press Enter in **Filter files** to open the first content result. The document opens beside your files and highlights the matched word on the page so you can see where it appears right away. ## Pins and Recent Above your file tree, the sidebar gives you quick access to the documents you pin and a history of everything you opened recently, grouped by day. ### Pins You can pin any active document that you can open (folders and uploaded files cannot be pinned). - To pin a document, open its `...` menu in the workspace header or its **Actions for** menu in the files table and click **Pin to sidebar**. - Pinned documents appear under the **Pinned** heading in the sidebar, below **Recent**, **Inbox**, **Shared with me**, and **Home**, and above the file tree. When you have no pinned documents, the **Pinned** section is hidden. - Pins are listed in the order you pinned them, oldest first. Hovering a pin shows the document name and its owner. - To remove a pin, open the document's menu and click **Unpin from sidebar**. You can pin up to 50 documents. If you try to pin a 51st document, Hyperclay shows **You can pin up to 50 documents. Unpin one first.** Any pinned documents that were later deleted or that you can no longer access are skipped in the sidebar and cleared automatically when you reach the 50-pin limit. ### Recent Click **Recent** near the top of the sidebar to see up to 50 documents you opened most recently. Opening a document again moves it to the top of the list. - Your history is grouped by your local calendar into **Today**, **Yesterday**, and **Earlier**. Empty groups are hidden. - The table lists each document's **Name**, **Opened** timestamp (a time of day under **Today** and **Yesterday**, or a date under **Earlier**), and **Updated** timestamp. - Your **Recent** list is private to your account (**Only you see this list**). --- # Uploads > Upload images and files to your workspace, see how per-document upload folders work, and preview or edit uploaded text files in the dashboard. Source: https://hyperclay.com/docs/uploads/ You can upload images, PDFs, text files, and other assets from the workspace dashboard or from inside a malleable document. Uploaded files live alongside your documents in the workspace, where you can preview them, edit text uploads in the code editor, or manage them like any other file. ## Upload files from the dashboard 1. Open the **New** menu and click **Upload files…**, or drag files from your computer onto the files table when it shows **Upload here**. 2. In the **Upload files** dialog, click **Choose files** to pick one or more files. The dialog displays your current storage usage (**`` MB of `` MB used**) and tracks each file through **Waiting**, **``% sent**, **Processing**, **Uploaded**, or **Failed**. 3. When an upload finishes, click **Copy link** (or **Copy all links**) to copy its URL, or click **Open file** to view it in the workspace. To let people upload files or crop images from a document's own code, use the [upload and quickcrop plugins](https://clayjs.com/docs/plugins/upload/). ## Where uploads live When a file is uploaded from inside a document, Hyperclay stores it in that document's own folder at `uploads/assets-document-/` (created automatically on the first upload) and links to it at `/_/uploads/assets-document-/`. The folder is named after the document's id, not its name, so renaming the document never moves its pictures or breaks their URLs, and two documents with the same name never share a folder. Because that `/_/uploads/assets-document-/` path resolves from the root of your account rather than relative to the document's current folder, all of the document's images and attachments keep working when you move the document into another folder. A file uploaded from inside a document belongs to that document, and where your account's uploaded files have been protected, its URL follows the document's read access: anyone the document is shared with can open the picture, and anyone who cannot open the document gets the same 404 the file would give if it did not exist. Change who can read the document and its pictures answer to that on the next request, so a document that becomes private takes its images with it. These files are also sent as `Cache-Control: private, no-store`, so no shared cache keeps a copy from a time when more people could read them. What that does not cover: files uploaded before this protection existed stay reachable by their URL until the account's protection migration has run, and a copy someone downloaded while a URL was public cannot be taken back. [HTML Clay](https://htmlclay.com/docs/uploads/) and [Hyperclay Local](https://hyperclaylocal.com/docs/metadata-and-uploads/) keep the older name-based folder, `assets-`, and their own file-serving rules apply to it rather than a shared-document access rule. The top-level `uploads` folder holds attachments for every document in your workspace, so it cannot be renamed, moved, or deleted. You can still rename, move, or delete individual uploaded files and subfolders inside `uploads`; see [Files and folders](https://hyperclay.com/docs/files/). ## Open an upload Click any uploaded file in the sidebar tree or files table to open it in the workspace beside your files: - **Images** (`png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`) render in place. - **PDFs** open in your browser's PDF viewer. - **Text files** (`txt`, `md`, `markdown`, `json`, `html`, `htm`, `htmlclay`, `jsx`, `css`, `js`, `mjs`, `csv`, `tsv`, `xml`, `yml`, `yaml`, `log`) display as plain text. - **Other files** show **This kind of file can't be shown here.** with **Download** and **Open in new tab** buttons. ### Edit a text file in the dashboard When you open a UTF-8 text file or an `.svg` upload and have permission to edit code, a **Code** tab appears at the top of the view. Click **Code** to edit the file in the [Code editor](https://hyperclay.com/docs/code-editor/), then click **Save** or press Cmd+S (Ctrl+S on Windows and Linux) to save your changes. Click **Close Code** to return to the preview. ## Limits Per-file and total upload storage limits depend on your [plan](https://hyperclay.com/docs/billing/): - **Free**: images only (PNG, JPG, GIF, WebP, AVIF or SVG), up to 10 MB per file, 25 MB total storage. - **Personal**: up to 20 MB per file, 500 MB total storage. - **Maker**: up to 100 MB per file, 2 GB total storage. Uploading a file larger than your plan's per-file limit returns **This file is larger than `` MB.** When your workspace reaches its storage cap, uploads stop with **Storage limit reached (``MB). Upgrade your plan for more storage.** From the dashboard **Upload files** dialog, you can upload any file type except `.shtml` and `.xht`. When uploading from inside a document's own upload lane, `.html`, `.htm`, `.xhtml`, `.htmlclay`, `.js`, `.mjs`, `.xml`, `.shtml`, and `.xht` are refused so HTML documents and scripts are saved through the document save lane instead. --- # Import and export > Import HTML pages or a Notion export into your workspace, and download a single document or your entire workspace as a zip. Source: https://hyperclay.com/docs/import-export/ You own every file in your workspace as standard HTML and uploaded assets. You can import standalone HTML files or zip archives such as Notion and Google Docs exports, download individual documents, or export your entire workspace as one zip file. ## Import To import pages into your workspace: 1. Navigate to the folder where you want the imported files placed. 2. Open the **New** menu and click **Import files…**. 3. In the **Import files** dialog, click **Choose files…** and pick one or more `.html`, `.htm`, `.htmlclay`, or `.zip` files from your computer. ### What you can import - **HTML files** (`.html`, `.htm`, `.htmlclay`): Each file you pick becomes a document in the current folder. You can select multiple HTML files at once. - **A Notion export**: In Notion, open a page's `...` menu, choose **Export**, pick **HTML**, and import the `.zip` file Notion downloads. Hyperclay strips Notion's 32-character IDs from page and folder names, turns subpages into folders, places images and attachments into your uploads, and rewrites links so they keep working. - **A Google Docs export**: In Google Docs, choose **File**, then **Download**, then **Web page (.html, zipped)**, and import the resulting `.zip`. - **Any `.zip` of HTML pages and assets**: Hyperclay creates a new folder named after the zip file, imports each HTML page as a document, moves non-page files (such as images, PDFs, or spreadsheets) into `uploads/import-/`, and rewrites relative links across your pages to point to the imported documents and uploads. System files such as `__MACOSX` and `.DS_Store` are skipped. > [!NOTE] > If a Notion export with subpages produces a zip that holds another zip inside it (**This zip holds another zip. Unzip it once and import the zip inside.**), unzip the outer file once on your computer and import the inner `.zip`. ### Import limits - **Page size**: Each HTML page can be up to 8 MB before and after link rewriting. In a zip import, pages larger than 8 MB are skipped and listed in the completion notice while the rest of the zip finishes importing. - **Zip size**: A zip archive must fit within your plan's per-file upload limit (20 MB on Personal, 100 MB on Maker; see [Uploads](https://hyperclay.com/docs/uploads/)), contain at most 2,000 entries, and expand to at most 200 MB uncompressed. - **Folder depth**: Imported subfolders cannot exceed the 5-level [folder depth](https://hyperclay.com/docs/files/) limit (**This folder is too deep to import into. Choose a folder higher up.**). - **One zip at a time**: Hyperclay runs one zip import at a time across the whole service. If another import is running, yours is refused with **Another zip import is running. Try again in a minute.** ## Export your workspace Anyone with view access to a workspace can download the entire workspace as a single zip archive: 1. Open **Account menu** (**My account**). 2. Click **Export workspace**. Your browser downloads `-hyperclay-.zip`. Only one export can run at a time per workspace; starting another while one is running shows **An export is already running**. ### What is inside the workspace zip - `README.txt` describing the archive layout. - Every folder and every document owned by the workspace (including private documents), saved as `.html` files with absolute `/_/uploads/...` links rewritten to local `/_/uploads/...` paths. - The `uploads/` folder, with every uploaded file you are allowed to open. - `MISSING.txt`, added only if any listed file had no stored content. Documents shared with you from another account, items in [Trash](https://hyperclay.com/docs/trash/), comments, [version history](https://hyperclay.com/docs/version-history/), custom domain settings, and account settings are not included in the zip. ## Download a single document To download one document from the hosted workspace, open its **Actions for** menu in the files table and click **Download**. Hyperclay saves the document as a single file under its own name, with its upload URLs rewritten to full links on your `hyperclay.com` address, so its images and attachments keep loading from anywhere. Pictures added to a private document are the exception: they load only for people who can open that document. To export a single document together with its attachments bundled as one `.zip` archive, use the desktop apps: see [Export as zip in HTML Clay](https://htmlclay.com/docs/export/) and [Export as zip in Hyperclay Local](https://hyperclaylocal.com/docs/export/). --- # Templates > Start a new document from a blank file or one of Hyperclay's templates, or save any document of your own as a reusable template. Source: https://hyperclay.com/docs/templates/ Every new document in Hyperclay starts on the **Start a new document** page. Name it if you like, pick a template, and create it. You can start from a blank HTML file, one of Hyperclay's templates, or a document you saved as a template in your own workspace. ## The New document page Open the **New** menu and click **New document**. The page has, from top to bottom: - **Document name**, marked **(optional)**. If you opened the page from inside a folder, a chip beside it says **In folder: ``**. - **Pick a template**: Hyperclay's templates, as cards. - **Templates in ``**: the templates saved in your own workspace, when there are any. - **Describe anything**, when [hosted AI](https://hyperclay.com/docs/hosted-ai/) is on for your account. ### Hyperclay's templates - **Blank**: An empty HTML file with [ClayJS](https://clayjs.com/docs/script-tag/) included, so you can write your own markup from scratch. - **Journal**: A private notebook for dated entries with titles and tags, kept in one HTML file. A Journal created from this gallery starts private, so only you can open it. - **Kanban**: A simple board to move work across lists, saved in one HTML file. Each card shows a picture of the template, its size and **ClayJS**. Click **Preview** on a card to see it large. In the preview, **Previous**, **Next** and the tabs move between templates, **Select card** picks that template, **Start with `