Build your own
Amoosed mode.

Get the amw command

Choose one installation source. Both commands below install the AmoosedWeb compiler as amw; use that command in every example on this page.

npm install -g amoosedweb-compiler
amw --version

dotnet tool install --global AmoosedWeb.Compiler
amw --version

After either install, start with amw init my-site. The amoosedweb-cli npm package is a compatibility name for existing installations; new projects can install the compiler directly.

Choose how media carries the app

The default string entry in bundle.json appends encoded chunks after any opaque binary file. For PNG images, png-chunk places them in a private ancillary chunk before IEND. For MP4 files, mp4-uuid places them in a UUID box after the existing boxes. png-pixels embeds encoded app chunks in opaque RGB low bits, wav-tones mixes repeated encoded chunks into a PCM audio cover, and frame-luma scatters a tiny shard across texture-selected, one-level pixel changes in an existing PNG frame. The browser verifies recovered ciphertext before serving the app.

"carriers": [
  {"path": "media/photo.png", "mode": "png-pixels"},
  {"path": "media/art.wav", "mode": "wav-tones", "maxChunks": 1},
  {"path": "media/frame.png", "mode": "frame-luma"},
  {"path": "media/clip.mp4", "mode": "mp4-uuid"}
]

Use real media files, keep originals for later builds, and test the generated media with your player and host. WAV mode rewrites audio as 16 kHz mono 8-bit PCM and holds only 4 KiB; optional maxChunks limits a WAV to 1–32 chunks for a shorter track. One luminance PNG frame holds at most 21 bytes. Keep another carrier for the favicon and larger assets. A CDN optimizer, image resizer, audio converter, or video transcoder can destroy embedded data. Container modes need verified byte ranges; pixel, audio, and frame modes fetch whole files. An external private index needs a byte-addressable first carrier.

Share a file or folder through sound or video

The standalone exchange tool encrypts a file or folder with your private media key, then writes one or more playable WAV tracks or MP4 videos. Send the complete numbered set to a friend and share the key separately. They can extract and verify the original filenames and bytes without an Amoosed website or extension. Preview the number and estimated size of output files with --dry-run before encoding; audio can be much larger than the input.

amw media-key .amw/keys/media.hex
amw audio-encode my-folder tones --dry-run
amw audio-encode my-folder tones
amw audio-decode tones restored-folder

amw video-encode my-folder cover.mp4 videos --dry-run
amw video-encode my-folder cover.mp4 videos
amw video-decode videos restored-folder

Set AMW_MEDIA_KEY_HEX from your private key file before encoding or decoding. Decode into a new folder: extraction verifies the archive, writes into a private staging folder, and publishes the result only after every file is written. WAV files contain repeated data tones. MP4 files retain the cover video and carry ciphertext in UUID boxes, so they require byte-preserving transfer: video platforms that transcode uploads can remove the data. Both methods split larger archives into multiple files. The CLI stages archives on disk and verifies extraction before publishing files; disk space and hosting limits still apply. Read the full media guide for the key workflow, formats, and limits.

Send encrypted data in carrier files

Use the compiler without making a website. carrier-embed puts an encrypted payload after any byte-preserving binary file and creates a fresh shared-secret key file. For a larger payload, carrier-embed-set spreads it across the files in a carrier folder. Share the resulting file or folder by email, drive, or another route that keeps the bytes intact; send the key separately.

amw carrier-embed cover.jpg note.txt sent.jpg secret.hex
amw carrier-verify sent.jpg secret.hex note.txt
amw carrier-extract sent.jpg secret.hex recovered-note.txt

amw carrier-embed-set covers/ archive.zip sent/ folder-secret.hex
amw carrier-verify-set sent/ folder-secret.hex archive.zip
amw carrier-extract-set sent/ folder-secret.hex recovered-archive.zip

Always verify against the original and test extraction before sending. The recipient should repeat both checks on the received files. Each output keeps the original carrier as its prefix. The single-file footer and encrypted folder-shard catalogue locate parts and detect corruption; the key authenticates and decrypts the payload. No loose index file is needed for a folder exchange. This shared key is separate from a website index key and its members key. The commands stream payloads in bounded blocks and publish extracted files only after verification; media conversion can remove appended bytes. Read the format and delivery limits ↗

Experiment with pixels, sound, and frames

The compiler also includes standalone media experiments for an image, album track, or video puzzle. It encrypts a small payload first, then puts ciphertext into PNG color bits, repeated audio tones, or numbered replacement frames. Audio can be a tone-only artwork, including a museum installation, or mixed into a cover soundtrack. The frame index records clip IDs, seconds, and frame numbers so the copies can be reconstructed.

PNG pixels, four-tone WAV, and individual sparse-pixel PNG frames are website carrier modes. The published demo uses all six website carrier modes, including a playable MP4 with a second film in its UUID box and that film's fingerprint in picture frames. Multi-clip frame sets and extraction from muxed video picture frames are not yet website app carriers. PNG low bits require lossless hosting; video transcoding and YouTube recovery remain unproven. The standalone frame-encode-set ... luma experiment still uses conspicuous tiles. See the media transport guide, exact commands, and limitations before using them for a release.

Tools and downloads

Use npm for the cross-platform compiler and Node.js reader. On Windows x64, NuGet also offers a .NET tool and C# reader. Install the Chrome extension from its official Web Store listing.

npmCompiler for Node.js npm · Windows, macOS, Linux

Requires Node.js 22 or newer. Installs the amw project compiler command.

npm install -g amoosedweb-compiler

AmoosedWeb Compiler on npm ↗

npmReader for Node.js npm · Windows, macOS, Linux

Import verified resource listing and download functions into your app.

npm install amoosedweb-reader

AmoosedWeb Reader on npm ↗

npmCompatibility CLI npm · existing users

amoosedweb-cli remains a thin compatibility package for the matching compiler and reader.

npm install -g amoosedweb-cli

AmoosedWeb CLI on npm ↗

NuGetCompiler for .NET NuGet · Windows x64

A .NET 10 tool that installs the same amw command without a separate Node.js installation.

dotnet tool install --global AmoosedWeb.Compiler

Installation guide ↗

NuGetReader for C# NuGet · Windows x64

Use AmoosedWeb.Reader in a .NET 10 app. Its matching AmoosedWeb.Native runtime installs automatically.

dotnet add package AmoosedWeb.Reader

C# reader guide ↗

Chrome extension Chrome Web Store

Add the Amoosed mode switch to desktop Chrome, then visit an Amoosed-enabled website and select the moose icon.

Native C/C++ Reader SDK ZIP · Windows x64 preview

Public headers, prebuilt C and C++ libraries, CMake targets, and examples. Preview C ABI revision 16.

Download native Reader ZIP ↓
Native SDK details ↗

Agent skills Codex and Claude · included in each starter

CodexClaude

amw init includes the site, maintenance, and Pages skills. amw init-share includes share, maintenance, and Pages skills. Both generate AGENTS.md and a CLAUDE.md pointer. Add optional media or Reader skills to any existing project, and refresh installed skills after upgrading amw.

amw install-skill my-site codex media
amw update-skill my-site

Read what each skill does ↗
Download all six skills as a ZIP ↓

Run amw open-extension to open the official Chrome Web Store listing. Package managers install the version available in their registries. The .NET Native support package is a dependency of the Reader, not a separate end-user command. Plain-text command reference.

From Hello World to a live site

1. Create a project

   After installing amw from npm or NuGet, create a starter:

   amw init my-site

   The new folder is its own Git repository and already contains the relevant Codex and Claude skills.

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.

amw 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. Chrome streams verified file parts to its save dialog and completes the save only after the final hash passes. Browsers without a streaming save picker use a 64 MiB fallback. 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. If your host cannot deploy the generated static folder, you must provide these same-origin routes through its own routing system; the compiler does not install a generic server adapter.

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.

Read a published site from a terminal

The compiler includes a read-only remote client. It loads a verified favicon index or a privately shared .amwkey, lists virtual files and their sizes, and downloads each file after checking every chunk and the assembled SHA-256. This works without the Chrome extension. Install it from npm with Node.js 22 or newer, or use the Windows x64 .NET tool.

amw remote-list https://example.com/ [private.amwkey]
amw remote-get https://example.com/ /amoosed.com/app/files/game.zip game.zip [private.amwkey]
amw remote-pull https://example.com/ ./recovered-app [private.amwkey]

For protected member files, set AMW_MEMBER_KEY_FILE to an owner-shared .amwmember file or private 64-character hex key file. AMW_CONTENT_KEY_HEX is also accepted. The list shows member file metadata without that key; downloading protected files requires it. Downloads never overwrite existing files. Install amoosedweb-reader from npm to import openRemoteSite, listRemoteResources, downloadRemoteResource, and downloadRemoteSite into a Node.js app. Existing amoosedweb-cli/reader imports continue to work through the compatibility shim.

import { openRemoteSite, listRemoteResources, downloadRemoteResource } from 'amoosedweb-reader';
const site = await openRemoteSite('https://example.com/', { indexKeyFile: 'private.amwkey', memberKeyFile: 'members.amwmember' });
console.log(listRemoteResources(site));
await downloadRemoteResource(site, '/amoosed.com/app/files/game.zip', 'game.zip');

C# applications can use the .NET reader library with the matching native support package. The facade exposes ListAsync, DownloadAsync, and DownloadAllAsync, keeps member keys in files, and offers an explicit CLI constructor. Check the installed package version before relying on the native default. Read the .NET installation guide and C# example ↗.

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 a grouped overview or amw help bundle for exact arguments.