https://nomad.pages.dev/docs/api/ Recent content in API Documentation on Nomad.dev Hugo -- gohugo.io en-us https://nomad.pages.dev/docs/api/advanced/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/ Advanced topics for power users and developers. Webterm Forking Hyperdrives Comparing and Merging Hyperdrives Creating Mounts Editing File Metadata https://nomad.pages.dev/docs/api/apis/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/ JavaScript APIs available in Nomad. nomad.ai nomad.fs Private Drive nomad.shell nomad.panes nomad.peersockets nomad.capabilities nomad.contacts nomad.markdown nomad.terminal https://nomad.pages.dev/docs/api/beginner/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/ Get started building with Nomad. Creating New Hyperdrives Using the Editor Sharing Hyperdrives Hosting Hyperdrives Creating Files and Folders Importing and Exporting Files Changing a Drive's Title or Thumbnail https://nomad.pages.dev/docs/api/beginner/changing-a-drive-title-or-thumbnail/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/changing-a-drive-title-or-thumbnail/ Every hyperdrive has a title, description, and thumbnail. To change them, open the “Drive Properties” dialog and make your changes. You can reach this dialog in multiple ways. From the Site Info button Visit the drive, then click on the Site Info button (the blue button on the left side of the address bar). Then click “Tools” and select “Drive Properties.” From “My Library” Open a new tab and look for the “My Library” link in the top right. https://nomad.pages.dev/docs/api/advanced/collaborative-drives/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/collaborative-drives/ Every Drive in Nomad is an Autobase: multi-writer-capable, with a URL that stays the same for the drive’s entire life. Multiple Writers can append; reads are linearised across all writers into an eventually-consistent view. “Collaborative” is a policy flag, not a separate kind of drive. A drive is locked (single-writer) by default and can be unlocked without changing its URL — so a drive can start private and open up to collaborators later. https://nomad.pages.dev/docs/api/advanced/comparing-and-merging-hyperdrives/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/comparing-and-merging-hyperdrives/ Sometimes it’s useful to copy files between hyperdrives. This may be particularly useful after forking a hyperdrive and making some changes. To open the “Compare and Merge” interface, navigate to your hyperdrive, click on the Site Info button, go to the “Forks” submenu and click “Diff / Merge Original”. This will open the compare interface. Choose the source drive on the top left and the target drive on the right using the dropdowns. https://nomad.pages.dev/docs/api/beginner/creating-files-and-folders/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/creating-files-and-folders/ Using the Editor Access your hyperdrive and open the editor, then expand the files listing. Right-click in the files listing (but not on a file) and select “New file” or “New folder.” You’ll receive a prompt asking for the name before the item appears in your listing. Using the Files Explorer Open your hyperdrive and access the files explorer via “Explore Files.” Right-click in the files listing (but not on a file) and select “New file” or “New folder. https://nomad.pages.dev/docs/api/advanced/creating-mounts/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/creating-mounts/ “Mounting” is a tool which links one hyperdrive to another as a subfolder. Mounts are useful for a variety of use-cases. They can be used to make collections, to attach code-module dependencies, and more. A mounted drive will behave just like a subfolder. If you don’t “own” the mounted drive, it will be read-only, even if the containing drive is yours. In the editor Visit your hyperdrive and open the editor. https://nomad.pages.dev/docs/api/beginner/creating-new-hyperdrives/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/creating-new-hyperdrives/ You can create as many hyperdrives as you want. Each hyperdrive has its own URL. You share the URL so that other people can visit the hyperdrive. Only the creator of a hyperdrive can change its files. Visitors can only view the drive (though they can fork the hyperdrive to make their own copy). To create a new hyperdrive, click on the hamburger menu on the top right of the browser. https://nomad.pages.dev/docs/api/advanced/devices-and-the-vault/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/devices-and-the-vault/ Nomad lets you link several Devices (computers, phones) to one identity, so every Device can read and edit all of your Spaces and Drives. This page explains the model and how linking works. The Vault A Vault is a private, identity-level store that indexes your Spaces (by their Root Drive key) and your trusted Devices (by their writer key). It is the root of trust for multi-device: every Device you own is a Writer of the Vault. https://nomad.pages.dev/docs/api/advanced/editing-file-metadata/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/editing-file-metadata/ Files in Hyperdrive can have metadata values. Metadata is stored as a UTF-8 string. Each value is identified by a key string. You can put as many metadata values as you like on a file, but avoid going too far or you’ll slow down reads. In the editor Visit the file you want to modify and open the editor. Then click on the “File Metadata” button on the toolbar. A dropdown will appear with the metadata keys on the left and the values on the right. https://nomad.pages.dev/docs/api/advanced/forking-hyperdrives/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/forking-hyperdrives/ “Forking a hyperdrive” means creating a copy which is attached to its parent. Forking is useful during development flows. It creates a clone which tracks its origin. You can then easily compare and merge with the original drive. You may want to fork a drive when you want To work on a drive without publishing the changes immediately, or To work on a drive with other people. Creating forks To fork a hyperdrive, click on the Site Info button on the left side of the address bar. https://nomad.pages.dev/docs/api/faq/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/faq/ Why is Nomad different? Nomad is built with Chromium and should feel exactly like any other Web browser. The big difference: Nomad can host websites. Hosting a website is traditionally done by “servers” which are specialized computers in the cloud. Servers require a variety of skills to run, and while there are some great services out there to make it easier, we wanted to try something new. We figured, what if anybody could host a website from their laptop? https://nomad.pages.dev/docs/api/getting-started-with-nomad/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/getting-started-with-nomad/ Welcome! Nomad is a peer-to-peer browser for Web hackers. It includes a bunch of tools: Instant website creation A builtin editor A terminal environment Peer-to-peer Web APIs and more. In this guide, we’re going to familiarize you with Nomad’s ideas and tools. What is this peer-to-peer thing? Nomad uses a peer-to-peer protocol called Hypercore, or Hyper for short. “Hyperdrives” are like websites. They store webpages, pictures, media, user data, and so on. https://nomad.pages.dev/docs/api/help/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/help/ Troubleshooting and support resources. Hole-punchability https://nomad.pages.dev/docs/api/help/hole-punchability/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/help/hole-punchability/ Nomad’s peer-to-peer networking depends on hole-punching technology to enable device accessibility beyond local networks. When this fails, users may experience connectivity challenges. What the issue indicates The system alerts users when hole-punching isn’t functioning properly through a notification in the top right corner. “This doesn’t mean that all connections will fail, but it does mean that the odds of failed connection are higher.” Common causes Network routers and VPNs frequently lack support for hole-punching protocols. https://nomad.pages.dev/docs/api/beginner/hosting-hyperdrives/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/hosting-hyperdrives/ You can help keep other people’s hyperdrives online by contributing bandwidth. This is called “hosting.” To host a drive, visit the drive and click on the peer count on the right side of the address bar. You will see a toggle. Switch it to the green “on” state. You can turn off hosting by toggling the button again. https://nomad.pages.dev/docs/api/beginner/importing-and-exporting-files/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/importing-and-exporting-files/ In the editor Visit your hyperdrive and open the editor. Then expand the files listing by clicking on the ellipsis icon. Right-click in the files listing (but not on a file) and select “Import file(s)” or “Import folder(s)” to import files or folders, or “Export files” to export all files in the drive. You can export individual files or folders by right-clicking on the file and selecting “Export.” In the files explorer Visit your hyperdrive and open the files explorer by clicking “Explore Files. https://nomad.pages.dev/docs/api/developers/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/developers/ Every hyperdrive contains a manifest file at /index.json that stores metadata about the drive. Fields title String. A human-readable name for the drive. description String. A short description of the drive’s contents. type String. A type identifier that applications can use to interpret the drive’s purpose. Common values: "unwalled.garden/person" — a personal profile drive "unwalled.garden/website" — a general website thumb String. Path (within the drive) to the thumbnail image. https://nomad.pages.dev/docs/api/intermediate/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/intermediate/ Go further with Nomad’s features. Syncing with Folders Your System Drive https://nomad.pages.dev/docs/api/apis/nomad.ai/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.ai/ nomad.ai gives any Drive page access to a local AI agent. The underlying model runs in an external OpenAI-compatible server (Ollama, LM Studio, etc.) configured in Nomad settings. Configuration Global settings (Nomad → Settings → AI Settings): ai_base_url — base URL of your OpenAI-compatible runtime, e.g. http://localhost:11434/v1 ai_default_model — fallback model name when a Drive does not specify one, e.g. llama3.2:3b Per-Drive opt-in — add an ai key to your Drive’s /index. https://nomad.pages.dev/docs/api/apis/nomad.autobase/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.autobase/ nomad.autobase has been removed. Every drive in Nomad is now an Autobase, so its read/write and writer-management methods all live on the single nomad.fs API. // before var drive = nomad.autobase.collaborativeDrive(url) // after var drive = nomad.fs.drive(url) nomad.autobase.collaborativeDrive(url) → nomad.fs.drive(url) nomad.autobase.createCollaborativeDrive(...) → nomad.fs.createCollaborativeDrive(...) writer management (createInvite, claimInvite, requestAccess, listRequests, approveRequest, denyRequest, removeWriter, listWriters) → the same methods on nomad.fs See nomad.fs and the Collaborative Drives guide. https://nomad.pages.dev/docs/api/apis/nomad.capabilities/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.capabilities/ “Capabilities” are opaque URLs which map to hyperdrives while hiding the URL. The name comes from the capabilities security model. The purpose of capability URLs is to provide security primitives for constrained access to a hyperdrive. The default security model of a hyperdrive is that the pubkey URL provides read access locally and over the network. Because the pubkey is unchangeable, it’s impossible to revoke access to a pubkey once it’s acquired. https://nomad.pages.dev/docs/api/apis/nomad.contacts/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.contacts/ Deprecated. This API was deprecated. It now calls to nomad.shell APIs to access drives saved with the ‘contact’ tag. Applications should migrate to nomad.shell for new development. nomad.contacts.requestProfile() Displays a dialog to select one profile drive. Returns Promise<Object>. An object with url, title, and description properties. nomad.contacts.requestContact() Shows a selection dialog for one contact from the address book. Returns Promise<Object>. An object with url, title, and description properties. https://nomad.pages.dev/docs/api/apis/nomad.fs/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.fs/ nomad.fs is the API for hyper:// drives — reading and writing files, drive lifecycle (create/fork/configure), and multi-writer collaboration, all through one surface. Every drive is an Autobase (multi-writer-capable, with a stable URL for life). stat() returns real mtime, ctime, and size, and get(path, 'json') parses JSON for you. API nomad.fs.drive(url) Create a scoped drive handle. Its methods accept paths relative to the drive rather than full URLs. var drive = nomad. https://nomad.pages.dev/docs/api/apis/nomad.hyperdrive/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.hyperdrive/ nomad.hyperdrive has been removed. Every drive in Nomad is now an Autobase, and all reading, writing, and drive management goes through the single nomad.fs API. Migration is a near drop-in rename — the method names are the same: // before nomad.hyperdrive.drive(url).readFile('/index.json') // after nomad.fs.drive(url).readFile('/index.json') nomad.hyperdrive.X(...) → nomad.fs.X(...) for drive, readFile, writeFile, readdir, stat, query, watch, createDrive, forkDrive, configure, and the rest. See nomad.fs. https://nomad.pages.dev/docs/api/apis/nomad.markdown/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.markdown/ nomad.markdown.toHTML(md) Renders Markdown into HTML. md String. The Markdown to render. Returns String. var html = nomad.markdown.toHTML('# hello!') console.log(html) // => '<h1>Hello!</h1>' https://nomad.pages.dev/docs/api/apis/nomad.page/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.page/ nomad.page tells a page which drive it lives in and which route it was loaded at. It is the authoritative way for a drive frontend (a /.ui SPA) to learn its own URL — always prefer it over parsing location. On desktop the two agree (tabs have a real hyper:// origin), but on mobile the page renders inside a WebView where location.host and location.pathname are not reliable; nomad.page is provided directly by the host on both platforms, so the same frontend code works everywhere. https://nomad.pages.dev/docs/api/apis/nomad.panes/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.panes/ Nomad includes the ability to split the page into multiple panes which navigate independently. This API gives applications the ability to “attach” to other panes and coordinate their browsing as well as inject JS/CSS. Currently each pane can attach and manage one other pane at a time. The user must grant permission to use the panes API. API nomad.panes.setAttachable() Mark the pane as “attachable.” This will cause the attachment UI to display in the app’s status bar, even if the pane is not attached to anything. https://nomad.pages.dev/docs/api/apis/nomad.peersockets/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.peersockets/ Peersockets enable you to send and receive messages to peers on a hyperdrive. Technical background Hyperdrive establishes connections between users to send drive-data. Peersockets piggybacks on those connections by creating additional message-channels. The peersocket channel is separated into “topics” which are string IDs. You choose to handle messages in a topic by “joining” the topic. If you don’t join a topic, your device will still receive the messages, but they’ll be discarded. https://nomad.pages.dev/docs/api/apis/nomad.schemas/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.schemas/ The schemas API exposes walled.garden schema validation to template apps. Schemas are Zod-backed and Standard Schema compliant. Templates running in sandboxed Drive contexts can’t import npm modules directly — this API bridges that gap. API nomad.schemas.validate(type, data) Validate an object against a named schema. type String. A walled.garden/* type string. data Object. The data to validate. Returns { success: true, data } or { success: false, error } (synchronous). var result = nomad. https://nomad.pages.dev/docs/api/apis/nomad.shell/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.shell/ nomad.shell.drivePropertiesDialog(url) Create a dialog for editing the properties of the given hyperdrive. url String. The URL of the drive to view. Returns Promise<Void> await nomad.shell.drivePropertiesDialog(drive.url) nomad.shell.selectFileDialog([opts]) Create a dialog for selecting files or folders. opts Object title String. The title of the selection dialog. buttonLabel String. The label on the “OK” button. drive String. The initial drive to explore. defaultPath String. The initial path to explore. select Array<String>. https://nomad.pages.dev/docs/api/apis/nomad.terminal/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/nomad.terminal/ nomad.terminal.registerCommand(command) Register a Webterm page command. See the Webterm documentation on page commands. command Object handle Function. The command’s handling function. May be async. Accepts a single opts object as the first argument and then any number of positional arguments after. name String. The name of the command. help String. An optional help description of the command. usage String. An optional usage description of the command. Returns Void nomad. https://nomad.pages.dev/docs/api/apis/private-drive/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/apis/private-drive/ Every Nomad user has a private drive — your personal on-device storage, created automatically on first launch and persisted across sessions. It holds data that should live on your machine, like bookmarks and app preferences. Like every drive in Nomad it is an Autobase, reached through the single nomad.fs API. What makes it special is only that it is addressed by the well-known URL hyper://private/ and is not published to the public network. https://nomad.pages.dev/docs/api/beginner/sharing-hyperdrives/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/sharing-hyperdrives/ Each hyperdrive has its own URL. To share it, click on the Site Info button on the left side of the address bar and select “Copy URL.” The drive runs from your computer. You can see how many peers are connected by looking at the peer count in the address bar. https://nomad.pages.dev/docs/api/intermediate/syncing-with-folders/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/intermediate/syncing-with-folders/ Sometimes you want to work on a Hyperdrive using files that are outside of Nomad. This is common when you’re using your own source-control, like Git, or when you just want to use an editor outside of Nomad. In this case, you can use “folder sync.” Setup: new drive When you create a new hyperdrive, you can select a folder to sync by pressing the “From Folder” button. This will cause the drive to be created with the contents of that folder. https://nomad.pages.dev/docs/api/beginner/using-the-editor/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/beginner/using-the-editor/ Nomad includes a built-in editor for viewing and modifying hyperdrive source code. Opening the Editor Users can access the editor through two methods: right-clicking the page and selecting “Edit Source,” or using the keyboard shortcut Cmd+B on macOS or Ctrl+B on Windows/Linux. Saving Work To save your work, press the “Save” button or press Cmd+S (macOS) or Ctrl+S. The system automatically refreshes the page to reflect updates. Browsing Files To explore available files in the current hyperdrive, click on the ellipsis icon in the top left to view a file listing. https://nomad.pages.dev/docs/api/advanced/webterm/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/advanced/webterm/ Webterm is a web-based terminal environment that ships with Nomad. It is superficially similar to the Unix “bash” terminal, but designed specifically for the browser and Hyperdrive environment. Basic usage To open the terminal, press Ctrl+~ or click on the “Terminal” button on the toolbar of the browser. The terminal uses a command syntax that’s similar to “bash” in Unix. command [-s|--switch {param}] {param1} {param2} At this stage, there is no piping or sub-invocations. https://nomad.pages.dev/docs/api/intermediate/your-system-drive/ Mon, 01 Jan 0001 00:00:00 +0000 https://nomad.pages.dev/docs/api/intermediate/your-system-drive/ Nomad provides each user with an automatically generated private storage location called the “System Drive” for keeping personal data secure. It stores your saved hyperdrives, bookmarks, and more. You can access this drive through the browser menu by selecting “My Private Drive.” The system assigns each user’s drive a unique hyper://private/ domain address that cannot be shared with others, as “each user has their own hyper://private/ address.” This individual addressing ensures content remains confidential since the system drive holds sensitive user information.