Juice-Labs · cursor · Mar 16, 2026
diff --git a/docs/juice/troubleshooting/troubleshooting.md b/docs/juice/troubleshooting/troubleshooting.md
@@ -49,6 +49,17 @@ To connect to a remote GPU from an application that you are running through juic
 
 Check your Endpoint Security or Antivirus. If you see any warnings about blocked DLLs or executables, add an exception for **C:\Program Files\Juice GPU\juice**. If you are unable to do so, please contact your IT administrator. 
 
+### Linux installer (`get.juicelabs.co`) exits with an error.
+
+If the one-step installer fails, match the output to these common causes:
+
+- `INSTALL_JUICE_TOKEN is not set`: export or inline a valid M2M token in `INSTALL_JUICE_TOKEN`.
+- `Token check failed`: verify token validity and the controller host (default is `electra.juicelabs.co`, override with `INSTALL_JUICE_CONTROLLER`).
+- `Please correct the above errors`: check missing runtime libraries and `glibc` version. The installer requires `glibc >= 2.27`, `libatomic`, and `libnuma`; agent service install also requires `libvulkan`, `libgl`, and `libnvidia-encode`.
+- `Could not install service`: the script could not complete `juice agent service install` (most often missing agent runtime dependencies or invalid pool value).
+
+Common pitfall: if `INSTALL_JUICE_POOL` is not set, the installer still installs binaries but intentionally skips service creation/startup.
+
 ### My agent failed to start.
 
 Check to see if you're already running an agent.
diff --git a/docs/juice/user-guide/setup/installation.md b/docs/juice/user-guide/setup/installation.md
@@ -35,6 +35,55 @@ Log in to [app.juicelabs.co](https://app.juicelabs.co):
 
    ...replacing `juice_linux_release` with the filename of the downloaded archive.
 
+## Linux One-Step Installer (Agent Service)
+
+For Linux hosts that should run a persistent Juice agent service, you can use the installer script at `https://get.juicelabs.co`.
+
+### Prerequisites
+
+- `sudo` or root access
+- `systemd` or `openrc`
+- `curl` or `wget`
+- An M2M token (from `app.juicelabs.co`)
+
+### Common install patterns
+
+Install the Juice binary only (no service created):
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx sh -
+```
+
+Install and configure the agent service in a pool:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=<pool-id> sh -
+```
+
+Install against a custom controller:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=<pool-id> INSTALL_JUICE_CONTROLLER=<controller-host> sh -
+```
+
+Pass additional agent runtime flags to the service command:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=<pool-id> sh -s - --cache-size=16 --labels region=us-east
+```
+
+### Installer environment variables
+
+| Variable | Required | Notes |
+| --- | --- | --- |
+| `INSTALL_JUICE_TOKEN` | Yes | M2M token used for token validation and download authorization |
+| `INSTALL_JUICE_POOL` | No | Pool ID/name for service install; if omitted, the script installs binaries but does not install/start the agent service |
+| `INSTALL_JUICE_CONTROLLER` | No | Controller host (default: `electra.juicelabs.co`) |
+| `INSTALL_JUICE_VERSION` | No | Version to install (defaults to latest) |
+| `INSTALL_JUICE_USER` | No | Service user (default: `juice`) |
+| `INSTALL_JUICE_SKIP_ENABLE` | No | If `true`, do not enable service at boot |
+| `INSTALL_JUICE_SKIP_START` | No | If `true`, do not start service after install |
+
 ## (Optional) Adding juice to PATH 
 
 #### To enable your system to run `juice` from any directory: 

diff --git a/docs/juice/user-guide/setup/systerm-reqs.md b/docs/juice/user-guide/setup/systerm-reqs.md
@@ -14,6 +14,8 @@ Both the **Client** and **GPU Agent** are supported on Windows 10 and Windows 11
 
 The client and GPU agent are supported on Debian-based distributions (version 10 and greater, like Ubuntu 18.04) and Red Hat Enterprise Linux (RHEL) 8-based distributions, such as AlmaLinux 8 or greater. Other distributions with similar or newer release dates are also likely supported.
 
+For installer-script based installs, `glibc` 2.27 or newer is required.
+
 :::note
 Currently, only the client is supported when running in WSL on Windows.
 :::
@@ -48,6 +50,10 @@ If you're running on a virtual machine with graphics drivers that don't support
         sudo apt update && sudo apt install libatomic1 libnuma1
         ```
     :::
+
+The Linux installer validates these client-side runtime libraries before install:
+- `libatomic`
+- `libnuma`
 #### AlmaLinux 8 or greater, (RHEL)-based. 
 - The following packages must be installed: 
 
@@ -84,6 +90,8 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
 
     - libgl1 
 
+    - `libnvidia-encode` (provided by NVIDIA driver packages)
+
     - libglib2.0-0 
 
 
@@ -95,6 +103,11 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
         ```
     :::
 
+The Linux installer validates these additional agent-only libraries when a pool is provided during install:
+- `libvulkan`
+- `libgl`
+- `libnvidia-encode`
+
 #### AlmaLinux 8 or greater, (RHEL)-based. 
 - The following packages must be installed: 
 
@@ -105,6 +118,8 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
   - vulkan-loader
 
   - mesa-libGL
+
+  - `libnvidia-encode` (provided by NVIDIA driver packages)
 
   - glib2