From bce878ca8ea96427e2fcf1d784be84b92fc2798f Mon Sep 17 00:00:00 2001 From: YairEtzion Date: Sun, 5 Apr 2026 20:18:31 +0300 Subject: [PATCH] docs: remove Bun-runtime callout from remote-shell now that v0.4.0 ships binaries Follow-up to v0.4.0. The prebuilt amesh-agent binaries are live in the GitHub release, the npm postinstall actually downloads them, and `brew install ameshdev/tap/amesh` installs both amesh and amesh-agent. Verified end-to-end in a fresh Linux x64 Docker container: npm install -g @authmesh/agent@0.4.0 -> postinstall downloads binary which amesh-agent -> /usr/local/bin/amesh-agent (symlink to launcher) amesh-agent --version -> amesh-agent/0.4.0 amesh-agent agent start --help -> full command help (not topic help) No Bun wrapper required on supported platforms. Changes: landpage/src/routes/docs/remote-shell/+page.svelte - Re-add Homebrew install option for the server side (single tap installs both amesh and amesh-agent now). - Re-add binary tarball install option pointing at the combined amesh-{version}-{platform}-{arch}.tar.gz archive and extracting the amesh-agent binary. - Remove the amber 'Runtime requirement' callout that warned about the Bun dependency and the bun $(which amesh-agent) agent start wrapper. - Add a new 'Platform Support' section with a table listing the four supported targets (macOS arm64/x64, Linux x64/arm64) and the armv7 exclusion, so users can see at a glance where they stand. - Update the inline TOC to include the new Platform Support anchor. - Troubleshooting card for 'Handshake failed' no longer references the Bun wrapper; the armv7 entry is now framed as 'unsupported architectures only'. landpage/src/routes/docs/troubleshooting/+page.svelte - Reframe the 'requires Bun runtime' entry: on supported platforms this error should never appear (postinstall bundles Bun in the binary); if it does, most likely the postinstall couldn't reach GitHub releases. - Keep the armv7 fallback guidance as a secondary paragraph. - 'Handshake failed' entry no longer mentions the Bun wrapper. --- .../src/routes/docs/remote-shell/+page.svelte | 90 ++++++++++++------- .../routes/docs/troubleshooting/+page.svelte | 17 ++-- 2 files changed, 68 insertions(+), 39 deletions(-) diff --git a/landpage/src/routes/docs/remote-shell/+page.svelte b/landpage/src/routes/docs/remote-shell/+page.svelte index 31a4e5b..d7d253d 100644 --- a/landpage/src/routes/docs/remote-shell/+page.svelte +++ b/landpage/src/routes/docs/remote-shell/+page.svelte @@ -11,15 +11,16 @@ const { prev, next } = getDocNav('remote-shell'); - // Install method tabs. Until prebuilt binaries ship (see Runtime requirement - // callout below), npm is the only target-side install path. Homebrew and the - // binary tarball will be re-added once packages/agent ships compiled binaries - // through the release pipeline. + // Install method tabs. The Homebrew formula installs both `amesh` and + // `amesh-agent` from a single tap, and the release tarballs contain both + // binaries, so the controller and server sides just extract different + // binaries from the same archive. The npm tab shows two separate packages + // because @authmesh/cli and @authmesh/agent are published independently. const installMethods = [ { label: 'Homebrew', controller: 'brew install ameshdev/tap/amesh', - server: '# Not yet available for the agent — see the npm tab or the\n# "Runtime requirement" note below.', + server: 'brew install ameshdev/tap/amesh', }, { label: 'npm', @@ -29,7 +30,7 @@ { label: 'Binary', controller: 'curl -sLO https://github.com/ameshdev/amesh/releases/latest/download/amesh-darwin-arm64.tar.gz\ntar xzf amesh-darwin-arm64.tar.gz && sudo mv amesh /usr/local/bin/', - server: '# Not yet available — use npm install -g @authmesh/agent for now.', + server: 'curl -sLO https://github.com/ameshdev/amesh/releases/latest/download/amesh-linux-x64.tar.gz\ntar xzf amesh-linux-x64.tar.gz && sudo mv amesh-agent /usr/local/bin/', }, ]; let activeInstallMethod = $state(0); @@ -44,6 +45,7 @@ const tocItems = [ { id: 'install', label: 'Install' }, { id: 'setup', label: 'Setup' }, + { id: 'platforms', label: 'Platform Support' }, { id: 'usage', label: 'Usage' }, { id: 'security', label: 'Security Model' }, { id: 'env-vars', label: 'Environment Variables' }, @@ -165,26 +167,7 @@ amesh list

Shell access is opt-in. Pairing for HTTP API auth does not automatically grant shell access.

3. Start the agent

- - -
-
Runtime requirement
-

- The amesh-agent daemon currently requires Bun installed on the target because it uses Bun.spawn for PTY support. Until prebuilt binaries ship, start the agent through Bun: -

-
- # Install Bun on the target (once) -curl -fsSL https://bun.sh/install | bash - -# Then start the agent through Bun -bun $(which amesh-agent) agent start`} /> -
-

- Platform support: macOS (arm64, x64) and Linux (x64, arm64 — including Raspberry Pi 4/5 on 64-bit Pi OS). Linux armv7 (Raspberry Pi 3 and earlier, 32-bit Pi OS) is not supported because Bun does not ship for that architecture. -

-
- -
+
# On the target (server) — start the agent daemon amesh-agent agent start @@ -192,7 +175,54 @@ amesh-agent agent start amesh-agent agent start --relay wss://relay.authmesh.dev/ws --idle-timeout 60`} />

- Note the binary name: controller commands run through amesh; the agent daemon runs through amesh-agent. They are separate packages (@authmesh/cli and @authmesh/agent). + Note the binary name: controller commands run through amesh; the agent daemon runs through amesh-agent. They are separate packages (@authmesh/cli and @authmesh/agent), but brew install ameshdev/tap/amesh installs both. +

+ + + +
+

Platform Support

+

The amesh-agent daemon ships as a prebuilt binary on all supported platforms — no runtime install needed.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformInstall viaNotes
macOS (arm64)Homebrew · npm · tarballApple Silicon; uses Secure Enclave when signed
macOS (x64)Homebrew · npm · tarballIntel macs; falls back to Keychain
Linux (x64)Homebrew · npm · tarball · .debMost cloud VMs; uses TPM 2.0 when available
Linux (arm64)Homebrew · npm · tarballRaspberry Pi 4/5 on 64-bit Pi OS, Ampere, Graviton
Linux (armv7, 32-bit)Bun wrapper onlyRaspberry Pi 3 and earlier — see note below
+
+

+ Linux armv7 (Raspberry Pi 3 and earlier): Bun does not ship for 32-bit ARM. If you must run the agent on these devices, install Bun manually (if a third-party build is available for your arch) and run as bun $(which amesh-agent) agent start. Everything else (Pi 4/5 on 64-bit Pi OS, all modern ARM servers) is supported out of the box.

@@ -274,11 +304,11 @@ Filesystem Size Used Avail Use% Mounted on
"Handshake failed" / connection timeout
-
The agent is not running on the target. Start it with bun $(which amesh-agent) agent start (see the runtime requirement note above).
+
The agent is not running on the target. Start it with amesh-agent agent start and verify the relay is reachable from both sides.
-
"The agent daemon requires Bun runtime for PTY support"
-
You ran amesh-agent agent start under Node.js. The agent uses Bun.spawn for PTY, which doesn't exist in Node. Install Bun (curl -fsSL https://bun.sh/install | bash) and run as bun $(which amesh-agent) agent start.
+
"The agent daemon requires Bun runtime for PTY support" (armv7 only)
+
You're on an unsupported architecture (typically Raspberry Pi 3 or earlier, 32-bit Pi OS). The postinstall couldn't find a prebuilt binary for your arch and fell back to the JS entry, which needs Bun for PTY. If a Bun build exists for your arch, install it and run as bun $(which amesh-agent) agent start. On supported architectures (macOS arm64/x64, Linux x64/arm64) this error should not appear — if it does, see the Troubleshooting page for the full diagnostic flow.
"Refusing to run as root"
diff --git a/landpage/src/routes/docs/troubleshooting/+page.svelte b/landpage/src/routes/docs/troubleshooting/+page.svelte index 340790a..a29b018 100644 --- a/landpage/src/routes/docs/troubleshooting/+page.svelte +++ b/landpage/src/routes/docs/troubleshooting/+page.svelte @@ -129,18 +129,17 @@

The controller is paired but doesn't have shell permission. Run amesh grant <device-id> --shell on the target. Pairing alone doesn't grant shell access — it's a separate explicit permission.

-
"The agent daemon requires Bun runtime for PTY support"
-

You ran amesh-agent agent start under Node.js after npm install -g @authmesh/agent. The agent uses Bun.spawn with terminal mode for PTY — a Bun-only API with no Node equivalent. Until prebuilt binaries ship, install Bun on the target and run through it:

- 
# Install Bun (once)
-curl -fsSL https://bun.sh/install | bash
-
-# Start the agent through Bun
-bun $(which amesh-agent) agent start
-

Raspberry Pi 3 and earlier (armv7, 32-bit Pi OS) is not supported because Bun does not ship for that architecture. Use Pi 4 or Pi 5 on 64-bit Pi OS, or a different ARM host.

+
"The agent daemon requires Bun runtime for PTY support" (unsupported architectures only)
+

+ You should never see this on macOS (arm64/x64) or Linux (x64/arm64) — the npm postinstall downloads a prebuilt binary that bundles Bun, and amesh-agent agent start runs directly. If you do see it on a supported platform, the postinstall probably couldn't reach GitHub releases — check the install log for download errors and re-run npm rebuild @authmesh/agent with network access. +

+

+ On unsupported architectures (Raspberry Pi 3 and earlier, armv7 32-bit Pi OS), the postinstall falls back to the JS entry and the agent needs Bun for PTY. Bun does not ship for armv7, so you'd need a third-party Bun build. Most users should move to Pi 4/5 on 64-bit Pi OS or a different ARM host. +

"Handshake failed" / connection timeout
-

The agent is not running on the target. Start it with bun $(which amesh-agent) agent start (see the runtime requirement above). Also verify the relay is reachable from both sides (port 443 or whatever your self-hosted relay uses).

+

The agent is not running on the target. Start it with amesh-agent agent start, and verify the relay is reachable from both sides (port 443 or whatever your self-hosted relay uses).

"Refusing to run as root"