Build your own
Amoosed mode.

Downloads

The portable ZIP and npm tarball contain the same compiler version. Native executables are built for their host operating system and are not in this Pages download set. Plain-text README.

From Hello World to a live site

1. Install and create a project

   Extract the portable ZIP, keep runtime/ beside amw.cjs, and run:

   node amw.cjs init my-site

   On Windows you can use amw.cmd; on macOS or Linux use sh amw.sh. To use npm instead, download the tarball and run npm install -g ./amoosedweb-cli-0.15.0.tgz, then use amw in the commands below. The new folder is its own Git repository.

2. Edit both experiences

   Edit my-site/site/ for the normal website and its existing binary media. Edit my-site/app/ for Amoosed mode. The starter already has a public Hello World app and an encrypted members/ page. document.json controls the small boot introduction; bundle.json lists carrier paths and protected resources. Read my-site/README.txt for the project-specific walkthrough.

3. Build and preview

   cd my-site
   build.cmd              (Windows)
   sh build.sh            (macOS/Linux)

   Use the command for your operating system. The helper creates and verifies a fresh builds/local-NNNN/ folder. Run amw serve builds/local-0001 with the path it prints, then open the local address in Chrome. The first successful build creates a private members key under .amw/keys/; keep it out of Git and the public site.

4. Make a Pages release

   release.cmd YOUR_PAGES_PROJECT              (Windows)
   sh release.sh YOUR_PAGES_PROJECT            (macOS/Linux)

   This packages and verifies a fresh distribution/release-NNNN/pages/ without uploading. The adjacent DEPLOY.txt gives manual Wrangler steps. The compiler saves a source and key snapshot outside the upload. Use publish.cmd or sh publish.sh to package and upload in one guided run.

5. Upgrade later

   Commit or stash project changes, install the newer compiler, then run amw update-project my-site. It updates unchanged starter files and preserves customized files. Review and commit the project diff, then build a new distribution. Never edit generated carrier bytes or pages/ files by hand.

Publish to Cloudflare Pages

From inside your generated project, run publish.cmd YOUR_PAGES_PROJECT on Windows or sh publish.sh YOUR_PAGES_PROJECT on macOS/Linux. The helper builds a new verified release, checks its private backup, lists your Cloudflare Pages projects, opens Wrangler login if needed, and offers to create the project if it is absent. It then deploys only the verified pages/ folder. You choose when to run it; building or making a release never deploys.

cd my-site
publish.cmd my-pages-project                (Windows)
sh publish.sh my-pages-project              (macOS/Linux)

For an existing Pages project whose production branch differs from your Git branch, add it as the last argument, for example publish.cmd my-pages-project main. Wrangler may ask you to authorize Cloudflare in a browser. Choose Y when your project appears in the list or N to create it. Set your custom domain in the Cloudflare Pages dashboard after deployment. Keep .amw/, DEPLOY.txt, and the distribution manifest off the site. Test the deployed favicon, carrier bytes, app route, and downloads yourself; image optimization that rewrites carriers breaks the content. Cloudflare’s Direct Upload guide ↗

Share files with friends

The file-share starter creates a normal landing page and a private Amoosed file list. Give it files such as ZIP archives, photos, or an indie game build. The private app displays their original names and exact byte sizes, with verified Download buttons. Its index key stays outside the published website. The normal HTML does not link the carrier images, so an ordinary page visit does not download them; the Amoosed loader fetches the needed chunks after a recipient presents the key. Carrier URLs are still public if someone knows or guesses them; the key controls decoding, not HTTP access to carrier bytes.

node amw.cjs init-share game-share game.zip readme.pdf
cd game-share
build.cmd                                      (Windows)
publish.cmd my-game-share                    (Windows)

Use sh build.sh and sh publish.sh my-game-share on macOS/Linux. The compiler copies inputs into app/files/ and distributes their chunks across image carriers, targeting about 16 MiB per carrier so Pages’ 25 MiB file limit can be checked. The first build prints a private .amwkey and compatible ICO path under .amw/indexes/. Send one of these to friends, or make a private QR with amw key-link after you know the HTTPS site URL. Anyone who gets a copy of the key or QR can open this release. The current download code assembles each file in browser memory before saving; each resource is limited to 1 GiB and the starter accepts up to 4 GiB total. Test large game archives on the devices your friends use.

Configure the starter

The starter creates these editable paths. site/ holds the normal website and original binary media; app/ holds the second website; document.json holds the short boot introduction. The compiler-created .amw-template.json is an upgrade record and should stay in Git without hand editing. .amw/, public/, and distribution/ are ignored or generated.

A typical bundle.json looks like this:

{
  "document": "document.json",
  "carriers": ["media/scene.png", "media/another-photo.jpg"],
  "chunkSize": 65536,
  "keyId": "friends-1",
  "protected": ["members/"]
}

Carrier paths are relative to site/ and must name binary files already present there. Add more carriers to distribute a larger app. chunkSize controls the maximum app chunk size. keyId names the protected edition, and protected names app paths requiring its private content key. Leave protected resources out if the whole app is public. Add "indexDelivery":"external" when the app itself needs a separately shared index key. Rebuild into a fresh output folder after changing any of these values.

Using an existing website

Put your existing static build in site/, keep its normal pages and media, place the alternative app in app/, and list the exact existing carrier paths in bundle.json. The compiler modifies the selected binary files and adds the /amoosed.com/ boot and service-worker routes. Full app mode requires those origin-owned routes. Hosts must serve carrier bytes without recompression or stripping and support byte ranges for large files. WordPress needs a route adapter; the static Pages folder is not a drop-in WordPress plugin.

The public site can have a member-only area, but a shared key can be forwarded and already downloaded content cannot be revoked. Read the generated project README before distributing a key.

What the compiler builds

Key sharing and rotation

For an externally indexed site, the generated .amwkey or private ICO is a bearer key to that app release. The recipient opens the normal website and imports it from the Amoosed boot page. To make a scannable invitation, run:

amw key-link my-site/.amw/indexes/key-<digest>.amwkey https://your-site.example/ invitation.svg

The command writes an SVG QR and prints an HTTPS boot URL. The QR contains the site URL, encrypted-index locator, and key in the URL fragment. The fragment is not sent with the HTTP request; the page verifies it against the carrier before storing it for that site in browser storage.

Members can instead receive a separate .amwmember file or member QR. The starter creates the file under .amw/keys/. A members QR targets one protected app path:

amw member-link my-site/.amw/keys/hello-members.amwmember https://your-site.example/ /amoosed.com/app/members/index.html member.svg

Use amw rotate-project my-site members to replace the members key, site for the site-wide key, or both for both. Rebuild into a new output folder, publish the new index and all changed carriers together, and distribute the new credential. In hosted-index mode the site-wide key is public encoding, so rotating it alone does not revoke access. Previously copied keys, plaintext, or complete old releases cannot be recalled.

Privacy and physical QR invitations

You can put an invitation QR on a card, poster, or object and publish only the encrypted carrier files online. A person who has the physical QR can scan it to obtain the matching key and open the private Amoosed edition. The host need not run a membership server or collect identities. A separate members QR can unlock only the protected part after the app index is available.

A QR is a copyable bearer credential. Anyone who photographs, forwards, or posts it can share the same access. Use a public event poster only when everyone who sees it may enter; use a private card or direct message for a smaller audience. A shared key cannot prove who scanned it, enforce one person per key, or stop recipients saving decrypted content. This is useful for consent-based sharing and lightweight access control, not DRM.

The URL fragment normally stays out of the host’s HTTP request, but the scanner app, browser history or sync, screenshots, clipboard, and same-origin scripts may still expose it. After verification the site-owned browser runtime stores the key for that origin; the Amoosed side panel does not copy the member key into extension storage. The website and CDN can still see visits and may keep normal access logs. If you need stronger privacy, distribute the QR carefully, avoid third-party scripts on the site, use HTTPS, and publish a new key and carrier release when rotating access.

Command reference

amw init DIR

Create an independent starter Git project.

amw init-share DIR FILE [FILE...]

Create a private file-share starter with verified downloads.

amw build-project PROJECT OUT

Compile the site and app into one verified static folder.

amw serve DIR

Preview the built folder locally with range responses.

amw verify-site DIR

Check the index, referenced carrier chunks, and release layout.

amw package-pages PROJECT DISTRIBUTION NAME

Create a Pages upload folder, local verification inventory, deploy guide, and private source-and-key backup.

amw verify-managed DISTRIBUTION

Check generated file hashes before publishing.

amw verify-backup DISTRIBUTION

Check the matching local source-and-key snapshot.

amw deploy-pages DISTRIBUTION NAME

After owner login and project creation, verify and run Wrangler Pages deploy.

amw update-project PROJECT

Upgrade unchanged starter files after committing or stashing changes.

amw rotate-project PROJECT members|site|both

Prepare new keys for a fresh release.

amw key-link KEY.amwkey SITE_URL [QR.svg]

Make a private site-entry link and optional QR.

amw member-link KEY.amwmember SITE_URL PROTECTED_PATH [QR.svg]

Make a private members link and optional QR.

The compiler also has lower-level bundle, verify-bundle, unpack-bundle, pack, and unpack commands for integration with an existing build pipeline. Run amw --help for their exact arguments.