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"