docs: standardize embedded Linux install guides

gustavosbarreto · gustavosbarreto · commit 50f9772dc148 · 2026-07-03T17:27:58.000-03:00
Rewrite the Raspberry Pi guide around the single install-script path and
drop the broken Docker/Snap blocks (wrong env var names) and the outdated
headless setup that relied on the pre-Bookworm wpa_supplicant.conf method.

Standardize the verification step to an "Accept the device" section with
the same wording across Buildroot, Yocto, and Raspberry Pi.

Buildroot: create (not edit) the /etc/default/shellhub-agent env file to
match the external tree README, drop the QEMU section, and link the repo.

Yocto: fix the supported release (scarthgap is not in LAYERSERIES_COMPAT)
to styhead/whinlatter/wrynose, and link the layer repo.

Overview: frame the two paths (build into firmware vs install on a running
OS) and add Raspberry Pi to the section.
diff --git a/ui/apps/docs/src/pages/embedded-linux/buildroot.mdx b/ui/apps/docs/src/pages/embedded-linux/buildroot.mdx
@@ -37,15 +37,17 @@ Select **ShellHub** under **External options** in the menuconfig interface.
 
 ### 3. Configure the agent
 
-The external tree provides a root filesystem overlay for the agent's environment variables. Edit `../shellhub/rootfs_overlay/etc/default/shellhub-agent`:
+The external tree ships a root filesystem overlay for the agent's environment file. Create `rootfs_overlay/etc/default/shellhub-agent` in the external tree:
 
 ```bash
+$ cat > ../shellhub/rootfs_overlay/etc/default/shellhub-agent <<-EOF
 SERVER_ADDRESS="https://cloud.shellhub.io"
 TENANT_ID="<your-tenant-id-here>"
 PRIVATE_KEY="/etc/shellhub-agent.key"
+EOF
 ```
 
-The agent reads these variables at boot:
+The init script and systemd unit source this file and pass the variables to the agent at boot:
 
 | Variable | Required | Description |
 |----------|:--------:|-------------|
@@ -61,29 +63,13 @@ $ make BR2_EXTERNAL=../shellhub rootfs-ext2
 
 The resulting image includes the ShellHub agent, which starts automatically on boot.
 
-## Testing with QEMU
+## Accept the device
 
-Test your image locally before flashing by booting it with QEMU:
-
-```bash
-$ qemu-system-x86_64 \
-    -kernel output/images/bzImage \
-    -drive file=output/images/rootfs.ext2,format=raw \
-    -append "root=/dev/sda console=ttyS0" \
-    -m 512M \
-    -nographic \
-    -netdev user,id=n0,hostfwd=tcp::2222-:22 \
-    -device virtio-net-pci,netdev=n0
-```
-
-The agent connects to the configured ShellHub server on startup, and the device appears in the dashboard.
-
-## Verifying
-
-After booting the image, the device appears in the ShellHub dashboard with **Pending** status. Click **Accept** to approve it.
+After booting the image, the device appears as **Pending** on the Devices page in the dashboard. Accept it to start connecting.
 
 ## Next steps
 
 - [Embedded Linux Overview](/embedded-linux/overview) — Why embed the agent and how it works
 - [Yocto Project](/embedded-linux/yocto) — Alternative build system integration
 - [Agent Overview](/agent/overview) — Agent configuration reference
+- [shellhub-io/buildroot](https://github.com/shellhub-io/buildroot) — External tree source and README
diff --git a/ui/apps/docs/src/pages/embedded-linux/overview.mdx b/ui/apps/docs/src/pages/embedded-linux/overview.mdx
@@ -6,7 +6,10 @@ description: Integrate the ShellHub agent into embedded Linux firmware with Buil
 
 # Embedded Linux
 
-ShellHub provides first-class support for embedded Linux platforms. Instead of installing the agent after deployment, you embed it directly into your firmware image — the agent starts automatically on boot and connects to ShellHub without manual setup on each device.
+ShellHub runs on embedded Linux platforms. There are two ways to get the agent onto a device:
+
+- **Build it into your firmware** with [Buildroot](/embedded-linux/buildroot) or [Yocto](/embedded-linux/yocto). The agent is part of the rootfs and connects on first boot, with no per-device install step. This page covers that approach.
+- **Install it on a device already running an embedded OS** — for example a [Raspberry Pi](/embedded-linux/raspberry-pi) running Raspberry Pi OS — with the agent install script.
 
 ## Why embed the agent?
 
@@ -50,7 +53,8 @@ The exact variable names differ by build system. See the [Buildroot](/embedded-l
 
 ## Next steps
 
-- [Buildroot](/embedded-linux/buildroot) — BR2_EXTERNAL setup and QEMU testing
+- [Buildroot](/embedded-linux/buildroot) — BR2_EXTERNAL setup and configuration
 - [Yocto Project](/embedded-linux/yocto) — meta-shellhub layer configuration
+- [Raspberry Pi](/embedded-linux/raspberry-pi) — Install on a running Raspberry Pi OS
 - [Agent Overview](/agent/overview) — How the agent works under the hood
 - [Agent Development](/developers/agent-development) — Build the agent from source for custom platforms
diff --git a/ui/apps/docs/src/pages/embedded-linux/raspberry-pi.mdx b/ui/apps/docs/src/pages/embedded-linux/raspberry-pi.mdx
@@ -6,120 +6,49 @@ description: Install the ShellHub agent on Raspberry Pi running Raspberry Pi OS
 
 # Raspberry Pi
 
-Install the ShellHub agent on a Raspberry Pi running Raspberry Pi OS (Debian-based). Once installed, you can SSH into your Pi from anywhere through ShellHub — no port forwarding, no dynamic DNS, no VPN.
+Install the ShellHub agent on a Raspberry Pi running Raspberry Pi OS (Debian-based). Once installed, you can SSH into your Pi from anywhere through ShellHub — no port forwarding, no dynamic DNS, no VPN, even behind NAT or CGNAT.
 
 ## Prerequisites
 
 - Raspberry Pi (any model: Zero, 3, 4, 5) running Raspberry Pi OS (32-bit or 64-bit)
 - Internet connection on the Pi
 - A ShellHub account with a namespace
 
-## Install with the install script
+## Install the agent
 
-The fastest way. SSH into your Pi (or open a terminal) and run:
+SSH into your Pi (or open a terminal) and run:
 
 ```bash
 $ curl -sSf "https://cloud.shellhub.io/install.sh?tenant_id=YOUR_TENANT_ID" | sh
 ```
 
-Replace `YOUR_TENANT_ID` with your namespace's tenant ID (found in the namespace selector or Settings page). The script detects your Pi's architecture (armhf or arm64) and installs the appropriate agent binary.
+Replace `YOUR_TENANT_ID` with your namespace's tenant ID. You can also copy this command with the tenant ID already filled in from **Add Device** in the dashboard.
+
+The script auto-detects your Pi's architecture (`armv7l`/`aarch64`) and the best install method available. On a stock Raspberry Pi OS it installs the agent as a systemd service (`shellhub-agent`) that starts on boot and restarts on failure; if Docker or Podman is already present, it uses that instead. You don't need to pick a method or write a `docker run` command by hand.
 
 For self-hosted ShellHub, replace the URL with your server address:
 
 ```bash
 $ curl -sSf "https://your-server.example.com/install.sh?tenant_id=YOUR_TENANT_ID" | sh
 ```
 
-After installation, the agent starts automatically and the Pi appears as **Pending** in the ShellHub dashboard. Accept it to start connecting.
-
-## Install with Docker
-
-If your Pi has Docker installed:
-
-```bash
-$ docker run -d \
-  --name shellhub-agent \
-  --restart always \
-  --privileged \
-  --net host \
-  --pid host \
-  -v /:/host \
-  -v /dev:/dev \
-  -v /var/run/docker.sock:/var/run/docker.sock \
-  -v /etc/shellhub:/etc/shellhub \
-  -e SERVER_ADDRESS=https://cloud.shellhub.io \
-  -e TENANT_ID=<your-tenant-id> \
-  shellhubio/agent
-```
-
-Replace `<your-tenant-id>` with your namespace's tenant ID (found in the namespace selector or Settings page).
-
-See the [Docker guide](/agent/docker) for more options.
-
-## Install with Snap
+## Accept the device
 
-On Ubuntu-based Raspberry Pi OS or Ubuntu Server for Pi:
-
-```bash
-$ sudo snap install shellhub-agent
-$ sudo snap set shellhub-agent server-address=https://cloud.shellhub.io
-$ sudo snap set shellhub-agent tenant-id=<your-tenant-id>
-$ sudo snap start shellhub-agent
-```
-
-See the [Snap guide](/agent/snap) for details.
+Once the agent is running, the Pi appears as **Pending** on the Devices page in the dashboard. Accept it to start connecting.
 
 ## Connecting to your Pi
 
-Once the agent is running and the device is accepted:
-
-**Web terminal** — Click the terminal icon next to your Pi on the Devices page.
-
-**Native SSH** — Use the SSHID:
+Once the device is accepted, connect through the web terminal or any native SSH client using its SSHID:
 
 ```bash
 $ ssh pi@mynamespace.raspberrypi@cloud.shellhub.io
 ```
 
-Replace `pi` with your Pi's username, `mynamespace` with your namespace, and `raspberrypi` with the device hostname shown in the dashboard.
-
-## Headless setup
-
-For Pis deployed without a monitor or keyboard, install the agent as part of your provisioning process:
-
-1. Flash Raspberry Pi OS to an SD card
-2. Enable SSH on first boot (create an empty `ssh` file in the boot partition)
-3. Configure Wi-Fi if needed (`wpa_supplicant.conf` in boot partition)
-4. Boot the Pi and SSH in over your local network
-5. Run the install script
-6. Accept the device in ShellHub
+Replace `pi` with your Pi's username, `mynamespace` with your namespace, and `raspberrypi` with the device hostname. See [Connecting via SSH](/guides/connecting) for the full details.
 
 From this point on, you can reach the Pi through ShellHub regardless of network changes — even if it moves to a different Wi-Fi network, gets a new IP, or goes behind a NAT.
 
-## Embedded use cases
-
-If you're building a custom Linux image for Raspberry Pi with Buildroot or Yocto, you can embed the agent directly into the firmware. See [Embedded Linux](/embedded-linux/overview) for build system integrations.
-
-## Troubleshooting
-
-**Agent not starting** — Check the agent logs:
-
-```bash
-$ journalctl -u shellhub-agent -f
-```
-
-Or for Docker:
-
-```bash
-$ docker logs shellhub-agent
-```
-
-**Device shows as offline** — Make sure the Pi has internet access and can reach your ShellHub server on port 443. Test with:
-
-```bash
-$ curl -I https://cloud.shellhub.io
-```
-
-**Wrong architecture** — The install script auto-detects architecture. If it fails, check with `uname -m`. Raspberry Pi OS 32-bit reports `armv7l`, 64-bit reports `aarch64`.
+## Next steps
 
-**Permission denied after connecting** — The default user on Raspberry Pi OS is `pi` (older images) or your custom username (newer images). Make sure you're using the correct username in the SSHID.
+- [Connecting via SSH](/guides/connecting) — Web terminal and native SSH clients
+- [Agent Overview](/agent/overview) — How the agent works and its configuration
diff --git a/ui/apps/docs/src/pages/embedded-linux/yocto.mdx b/ui/apps/docs/src/pages/embedded-linux/yocto.mdx
@@ -10,7 +10,7 @@ Add the ShellHub agent to your Yocto-based Linux image using the meta-shellhub l
 
 ## Prerequisites
 
-- Yocto Project (scarthgap or another supported release — the meta-shellhub branches map to Yocto releases)
+- A Yocto Project release supported by the layer (currently `styhead`, `whinlatter`, or `wrynose` — see `LAYERSERIES_COMPAT` in the layer)
 - Internet access to fetch the agent source during build
 
 ## Setup
@@ -55,12 +55,13 @@ $ bitbake your-image
 
 The agent is included in the image and starts automatically on boot.
 
-## Verifying
+## Accept the device
 
-After booting the image, the device appears in the ShellHub dashboard with **Pending** status. Click **Accept** to approve it.
+After booting the image, the device appears as **Pending** on the Devices page in the dashboard. Accept it to start connecting.
 
 ## Next steps
 
 - [Embedded Linux Overview](/embedded-linux/overview) — Why embed the agent and how it works
 - [Buildroot](/embedded-linux/buildroot) — Alternative build system integration
 - [Agent Overview](/agent/overview) — Agent configuration reference
+- [shellhub-io/meta-shellhub](https://github.com/shellhub-io/meta-shellhub) — Yocto layer source
