From 60444f57ec7b3056c5b402afa22bf85688a82aff Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 17 Jul 2026 09:06:46 +0000 Subject: [PATCH 1/2] Reorder Linux install tabs: viam-agent first, manual second The Viam app's machine setup page no longer offers the AppImage manual install option for 64-bit Linux (aarch64, x86_64). Only viam-agent is presented. Reorder the CLI install tabs on viam-server.md to match, putting "Install using viam-agent (recommended)" first. Also clarify in common-errors.md that the FUSE requirement applies specifically to the manual AppImage install, not to viam-agent installs. Source: viamrobotics/app#12758 Co-Authored-By: Claude Opus 4.6 (1M context) Claude-Session: https://claude.ai/code/session_01RhXoqM4bsKamX8uQS4cbyk --- docs/monitor/common-errors.md | 8 +++++--- docs/reference/viam-server.md | 32 ++++++++++++++++---------------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/monitor/common-errors.md b/docs/monitor/common-errors.md index b13fa083c8..38f54ead81 100644 --- a/docs/monitor/common-errors.md +++ b/docs/monitor/common-errors.md @@ -104,9 +104,11 @@ This is only required for the first `ssh` connection you make to a newly-imaged **Related Error:** `dlopen(): error loading libfuse.so.2` -**Description:** `viam-server` is distributed for Linux as an [AppImage](https://appimage.org/), which requires FUSE (Filesystem-in-Userspace) version 2. -FUSE version 2 is included in almost all modern Linux distributions by default, but some older Linux distros or minimal installs might not provide it out of the box, and some newer systems may ship with FUSE version 3 installed by default, which is not compatible with `viam-server`. -For example, the latest Raspberry Pi OS (Debian GNU/Linux 12 bookworm) includes FUSE version 3 as its default FUSE installation, and requires FUSE version 2 to be installed as well to support `viam-server`. +**Description:** When installed manually using the AppImage binary, `viam-server` requires FUSE (Filesystem-in-Userspace) version 2. +If you installed `viam-server` using `viam-agent` (the recommended method), you should not encounter this error. + +FUSE version 2 is included in almost all modern Linux distributions by default, but some older Linux distros or minimal installs might not provide it out of the box, and some newer systems may ship with FUSE version 3 installed by default, which is not compatible with the AppImage. +For example, the latest Raspberry Pi OS (Debian GNU/Linux 12 bookworm) includes FUSE version 3 as its default FUSE installation, and requires FUSE version 2 to be installed as well. In addition, if you are installing `viam-server` within a Docker container, you may also experience this error due to its default security restrictions. FUSE is not required for macOS installations of `viam-server`. diff --git a/docs/reference/viam-server.md b/docs/reference/viam-server.md index e4e7f23205..106c1a4ba4 100644 --- a/docs/reference/viam-server.md +++ b/docs/reference/viam-server.md @@ -320,6 +320,15 @@ If you need to install `viam-server` without the web UI, you can run the followi {{< tabs >}} {{% tab name="Linux (Aarch64)" %}} {{< tabs >}} +{{% tab name="Install using viam-agent (recommended)" %}} + +```sh {id="terminal-prompt" class="command-line" data-prompt="$"} +sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" +``` + +The `viam-agent` and `viam-server` binaries are installed at /opt/viam/bin/viam-server. + +{{% /tab %}} {{% tab name="Install manually" %}} ```bash {class="line-numbers linkable-line-numbers"} @@ -335,7 +344,13 @@ chmod 755 viam-server && sudo ./viam-server --aix-install The `viam-server` binary is installed at /usr/local/bin/viam-server. {{% /tab %}} -{{% tab name="Install using viam-agent" %}} +{{< /tabs >}} + +{{% /tab %}} +{{% tab name="Linux (x86_64)" %}} + +{{< tabs >}} +{{% tab name="Install using viam-agent (recommended)" %}} ```sh {id="terminal-prompt" class="command-line" data-prompt="$"} sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" @@ -344,12 +359,6 @@ sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/a The `viam-agent` and `viam-server` binaries are installed at /opt/viam/bin/viam-server. {{% /tab %}} -{{< /tabs >}} - -{{% /tab %}} -{{% tab name="Linux (x86_64)" %}} - -{{< tabs >}} {{% tab name="Install manually" %}} ```bash {class="line-numbers linkable-line-numbers"} @@ -364,15 +373,6 @@ chmod 755 viam-server && sudo ./viam-server --aix-install The `viam-server` binary is installed at /usr/local/bin/viam-server. -{{% /tab %}} -{{% tab name="Install using viam-agent" %}} - -```sh {id="terminal-prompt" class="command-line" data-prompt="$"} -sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" -``` - -The `viam-agent` and `viam-server` binaries are installed at /opt/viam/bin/viam-server. - {{% /tab %}} {{< /tabs >}} {{% /tab %}} From 05db2eef56413097c195ef582ff3f2b883ff59f6 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Jul 2026 18:47:02 +0000 Subject: [PATCH 2/2] Remove 64-bit Linux AppImage references per reviewer feedback Per ale7714's review: AppImage is no longer valid for 64-bit Linux (aarch64, x86_64). Only 32-bit ARM (armhf) AppImage remains. - viam-server.md: Remove "Install manually" tabs for both 64-bit Linux architectures, keeping only the viam-agent install command - jetson-agx-orin-setup.md: Remove AppImage fallback URLs (2 places) - jetson-nano-setup.md: Remove AppImage fallback URL - architectures.md: Replace AppImage commands with viam-agent - common-errors.md: Clarify FUSE error applies to 32-bit ARM only Co-Authored-By: Claude Opus 4.6 (1M context) Claude-Session: https://claude.ai/code/session_01RhXoqM4bsKamX8uQS4cbyk --- docs/monitor/common-errors.md | 9 ++--- .../device-setup/jetson-agx-orin-setup.md | 10 ++--- .../device-setup/jetson-nano-setup.md | 4 +- docs/reference/viam-server.md | 40 ------------------- static/include/install/architectures.md | 8 +--- 5 files changed, 10 insertions(+), 61 deletions(-) diff --git a/docs/monitor/common-errors.md b/docs/monitor/common-errors.md index 38f54ead81..20a1be062b 100644 --- a/docs/monitor/common-errors.md +++ b/docs/monitor/common-errors.md @@ -104,18 +104,17 @@ This is only required for the first `ssh` connection you make to a newly-imaged **Related Error:** `dlopen(): error loading libfuse.so.2` -**Description:** When installed manually using the AppImage binary, `viam-server` requires FUSE (Filesystem-in-Userspace) version 2. -If you installed `viam-server` using `viam-agent` (the recommended method), you should not encounter this error. +**Description:** On 32-bit ARM Linux (armhf), `viam-server` is distributed as an [AppImage](https://appimage.org/), which requires FUSE (Filesystem-in-Userspace) version 2. +On 64-bit Linux (aarch64, x86_64) and macOS, install `viam-server` using [`viam-agent`](/reference/viam-agent/) instead. You will not encounter this error with `viam-agent`. FUSE version 2 is included in almost all modern Linux distributions by default, but some older Linux distros or minimal installs might not provide it out of the box, and some newer systems may ship with FUSE version 3 installed by default, which is not compatible with the AppImage. For example, the latest Raspberry Pi OS (Debian GNU/Linux 12 bookworm) includes FUSE version 3 as its default FUSE installation, and requires FUSE version 2 to be installed as well. In addition, if you are installing `viam-server` within a Docker container, you may also experience this error due to its default security restrictions. -FUSE is not required for macOS installations of `viam-server`. {{% alert title="Important" color="note" %}} -`viam-server` requires FUSE version 2 (`libfuse2`), _not_ FUSE version 3 (`fuse3` or `libfuse3`) or versions of FUSE previous to FUSE version 2 (`fuse`). -To support a `viam-server` installation, you must install `libfuse2`. +The AppImage requires FUSE version 2 (`libfuse2`), _not_ FUSE version 3 (`fuse3` or `libfuse3`) or versions of FUSE previous to FUSE version 2 (`fuse`). +To resolve this error, you must install `libfuse2`. {{% /alert %}} **Solution:** If you receive this error, install FUSE version 2 on your Linux system according to one of the following steps: diff --git a/docs/reference/device-setup/jetson-agx-orin-setup.md b/docs/reference/device-setup/jetson-agx-orin-setup.md index 82ca4edbb3..daa085ecca 100644 --- a/docs/reference/device-setup/jetson-agx-orin-setup.md +++ b/docs/reference/device-setup/jetson-agx-orin-setup.md @@ -78,11 +78,9 @@ If you intend to use GPIO, however, we recommend installing Jetpack 5 on your Je Look at the Troubleshooting section below for help navigating these instructions. Once you have reached _Next Steps_, return to the Viam docs. -{{< alert title="Tip: viam-server installation with curl" color="tip" >}} +{{< alert title="Tip: curl installation" color="tip" >}} -If `curl` is not installed on your Orin, run `sudo apt install curl` before downloading the `viam-server` binary. - -If this command fails, try using `wget https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-latest-aarch64.AppImage` to download the `viam-server` binary. +If `curl` is not installed on your Orin, run `sudo apt install curl` before proceeding with installation. {{% /alert %}} @@ -150,9 +148,7 @@ To use your Jetson board, follow the [setup guide](/set-up-a-machine/first-machi ### Install `curl` -If `curl` is not installed on your Orin, run `sudo apt install curl` before downloading the `viam-server` binary. - -If this command fails, try using `wget https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-aarch64.AppImage` to download the `viam-server` binary. +If `curl` is not installed on your Orin, run `sudo apt install curl` before proceeding with installation. You can find additional assistance in the [Troubleshooting section](/monitor/troubleshoot/). diff --git a/docs/reference/device-setup/jetson-nano-setup.md b/docs/reference/device-setup/jetson-nano-setup.md index 2de3e3a74e..43c420717b 100644 --- a/docs/reference/device-setup/jetson-nano-setup.md +++ b/docs/reference/device-setup/jetson-nano-setup.md @@ -109,9 +109,7 @@ To use your Jetson board, follow the [setup guide](/set-up-a-machine/first-machi ### Install `curl` -If `curl` is not installed on your Orin, run `sudo apt install curl` before downloading the `viam-server` binary. - -If this command fails, try using `wget https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-aarch64.AppImage` to download the `viam-server` binary. +If `curl` is not installed on your Nano, run `sudo apt install curl` before proceeding with installation. ### Barrel jack power supply polarity diff --git a/docs/reference/viam-server.md b/docs/reference/viam-server.md index 106c1a4ba4..c1377f379f 100644 --- a/docs/reference/viam-server.md +++ b/docs/reference/viam-server.md @@ -319,8 +319,6 @@ If you need to install `viam-server` without the web UI, you can run the followi {{< tabs >}} {{% tab name="Linux (Aarch64)" %}} -{{< tabs >}} -{{% tab name="Install using viam-agent (recommended)" %}} ```sh {id="terminal-prompt" class="command-line" data-prompt="$"} sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" @@ -328,53 +326,15 @@ sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/a The `viam-agent` and `viam-server` binaries are installed at /opt/viam/bin/viam-server. -{{% /tab %}} -{{% tab name="Install manually" %}} - -```bash {class="line-numbers linkable-line-numbers"} -curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-aarch64.AppImage -o viam-server -``` - -Next, to make the `viam-server` executable and install as a system service, run the following command: - -```bash {class="line-numbers linkable-line-numbers"} -chmod 755 viam-server && sudo ./viam-server --aix-install -``` - -The `viam-server` binary is installed at /usr/local/bin/viam-server. - -{{% /tab %}} -{{< /tabs >}} - {{% /tab %}} {{% tab name="Linux (x86_64)" %}} -{{< tabs >}} -{{% tab name="Install using viam-agent (recommended)" %}} - ```sh {id="terminal-prompt" class="command-line" data-prompt="$"} sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" ``` The `viam-agent` and `viam-server` binaries are installed at /opt/viam/bin/viam-server. -{{% /tab %}} -{{% tab name="Install manually" %}} - -```bash {class="line-numbers linkable-line-numbers"} -curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-x86_64.AppImage -o viam-server -``` - -Next, to make the `viam-server` executable and install as a system service, run the following command: - -```bash {class="line-numbers linkable-line-numbers"} -chmod 755 viam-server && sudo ./viam-server --aix-install -``` - -The `viam-server` binary is installed at /usr/local/bin/viam-server. - -{{% /tab %}} -{{< /tabs >}} {{% /tab %}} {{% tab name="macOS" %}} diff --git a/static/include/install/architectures.md b/static/include/install/architectures.md index dd4c84b11c..5b05be23fd 100644 --- a/static/include/install/architectures.md +++ b/static/include/install/architectures.md @@ -2,19 +2,15 @@ {{% tab name="Aarch64"%}} ```sh {class="command-line" data-prompt="$"} -curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-aarch64.AppImage -o viam-server && chmod 755 viam-server && sudo ./viam-server --aix-install +sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" ``` -You can also use the latest version with [https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-latest-aarch64.AppImage](https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-latest-aarch64.AppImage). - {{% /tab %}} {{% tab name="X86_64"%}} ```sh {class="command-line" data-prompt="$"} -curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-x86_64.AppImage -o viam-server && chmod 755 viam-server && sudo ./viam-server --aix-install +sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" ``` -You can also use the latest version with [https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-x86_64.AppImage](https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-x86_64.AppImage). - {{% /tab %}} {{< /tabs >}}