Juice-Labs · cursor · Mar 9, 2026
diff --git a/docs/juice/troubleshooting/troubleshooting.md b/docs/juice/troubleshooting/troubleshooting.md
@@ -49,6 +49,40 @@ 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: `Token check failed`
+
+If you are using `curl https://get.juicelabs.co | ... sh -` and see `Token check failed`:
+
+- Verify `INSTALL_JUICE_TOKEN` is valid and not expired.
+- If using a non-default controller, set `INSTALL_JUICE_CONTROLLER=<your-controller-host>`.
+- Confirm outbound HTTPS access to your controller from the host.
+
+### Linux installer: missing library errors
+
+The installer validates required libraries before installing:
+
+- Client requirements: `libnuma`, `libatomic`
+- Agent requirements: `libvulkan`, `libgl`, `libnvidia-encode`
+
+If `INSTALL_JUICE_POOL` is set, missing agent libraries fail installation.
+If `INSTALL_JUICE_POOL` is not set, missing agent libraries are warnings (client-only install).
+
+### Linux installer: no service was created
+
+The install script only creates and starts the `juice` service when `INSTALL_JUICE_POOL` is provided.
+
+Example (creates service):
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=<pool-id-or-name> sh -
+```
+
+Example (binary-only install, no service):
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx sh -
+```
+
 ### 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
@@ -4,62 +4,115 @@ sidebar_position: 2
 ---
 # Installation
 
-Welcome to Juice! This guide will walk you through the installation process.
+Use this page for both desktop/client installation and Linux agent installation.
 
 Before you begin, make sure you have:
-- An account on [app.juicelabs.co](https://app.juicelabs.co) (if you don't have one, sign up or reach out to info@juicelabs.co)
+- An account on [app.juicelabs.co](https://app.juicelabs.co)
 - Administrator privileges on your system
-- At least 500MB of free disk space
+- At least 500 MB of free disk space
 
-Log in to [app.juicelabs.co](https://app.juicelabs.co):
+## Desktop App Or CLI Binary Install
+
+Log in to [app.juicelabs.co](https://app.juicelabs.co) and open the Downloads area:
 
 ![Download links](/img/juice/download_links.png)
 
 ### Windows
-1. Click on the download link for the Windows release.
-2. Run the installer and follow the steps outlined in the installation wizard.
+1. Download the Windows release.
+2. Run the installer and follow the wizard.
+
+### Linux (Manual Archive)
+1. Download the Linux release archive.
+2. Extract it:
+
+```bash
+tar -xf [juice_linux_release].tar
+```
+
+Replace `juice_linux_release` with your downloaded filename.
+
+## Linux Agent Installer Script
+
+For bare metal or VM hosts, use the hosted installer script:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=<pool-id-or-name> sh -
+```
+
+This installs Juice and configures a `juice` service (systemd or openrc) when `INSTALL_JUICE_POOL` is provided.
+
+### Common Installer Examples
+
+Install and configure an agent service:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=lab sh -
+```
+
+Install client binaries only (no service):
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx sh -
+```
+
+Use a custom controller:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=lab INSTALL_JUICE_CONTROLLER=controller.example.com sh -
+```
+
+Pass runtime args to the service command:
+
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=lab sh - --cache-size=16
+```
 
+Equivalent via `INSTALL_JUICE_EXEC`:
 
-### Linux
-1. Click the download link for the Linux release. 
+```bash
+curl https://get.juicelabs.co | INSTALL_JUICE_TOKEN=m2m_xxx INSTALL_JUICE_POOL=lab INSTALL_JUICE_EXEC="--cache-size=16" sh -
+```
 
-    :::note
-    Depending on your Linux configuration, you may need to download the file on a different system and transfer it to the Linux system where you intend to run Juice. 
-    :::
-
-2. Unzip the downloaded file: 
+### Key Installer Environment Variables
 
-    ```powershell
-    tar -xf [juice_linux_release].tar 
-    ```
+| Variable | Required | Description |
+| --- | --- | --- |
+| `INSTALL_JUICE_TOKEN` | Yes | M2M token used to authenticate and fetch releases. |
+| `INSTALL_JUICE_POOL` | No | Pool ID/name for agent service install. If omitted, no service is created. |
+| `INSTALL_JUICE_CONTROLLER` | No | Custom controller host. Defaults to `electra.juicelabs.co`. |
+| `INSTALL_JUICE_VERSION` | No | Version to install. Defaults to latest available release. |
+| `INSTALL_JUICE_EXEC` | No | Extra arguments injected into the service start command. |
+| `INSTALL_JUICE_SKIP_ENABLE` | No | If `true`, installer does not enable/start the service. |
+| `INSTALL_JUICE_SKIP_START` | No | If `true`, installer enables but does not start the service. |
 
-   ...replacing `juice_linux_release` with the filename of the downloaded archive.
+### Installer Constraints
 
-## (Optional) Adding juice to PATH 
+- `INSTALL_JUICE_TOKEN` is required.
+- `INSTALL_JUICE_POOL` is optional.
+- If `INSTALL_JUICE_POOL` is not set, the installer does not create/start a service.
+- The installer requires either `systemd` or `openrc` to manage a service.
+- The service name created by the installer is `juice`.
 
-#### To enable your system to run `juice` from any directory: 
+For Linux dependency requirements and package guidance, see [System Requirements](./systerm-reqs).
 
-1. Open your shell's configuration file in a text editor:
+## Optional: Add `juice` To PATH
 
-    ```powershell
-    nano ~/.bashrc
-    ```
+If you installed manually and want `juice` available from any shell directory:
 
-2. Add the following at the end of the file:
+1. Open your shell config (example):
 
-    ```powershell
-    export PATH=$PATH:/path/to/juice_directory
-    ```
+```bash
+nano ~/.bashrc
+```
 
-...replacing `/path/to/juice_directory` with the actual path to the directory containing the Juice executable. 
+2. Add:
 
-3. Save and exit the editor. 
-    :::tip
-    In nano, you can save and exit by pressing Ctrl+X, then Y, then Enter. 
-    :::
+```bash
+export PATH=$PATH:/path/to/juice_directory
+```
 
-4. Apply the changes to your current session: 
+3. Reload your shell config:
 
-    ```powershell
-    source ~/.bashrc 
-    ```
+```bash
+source ~/.bashrc
+```
diff --git a/docs/juice/user-guide/setup/systerm-reqs.md b/docs/juice/user-guide/setup/systerm-reqs.md
@@ -35,7 +35,7 @@ If you're running on a virtual machine with graphics drivers that don't support
 ### Linux 
 
 #### Ubuntu 18.04 or greater, Debian 10 or greater. 
-- The following packages must be installed: 
+- The following packages must be installed for the client:
 
     - libatomic1 
 
@@ -49,7 +49,7 @@ If you're running on a virtual machine with graphics drivers that don't support
         ```
     :::
 #### AlmaLinux 8 or greater, (RHEL)-based. 
-- The following packages must be installed: 
+- The following packages must be installed for the client:
 
   - libatomic
 
@@ -74,7 +74,8 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
 ### Linux 
 
 #### Ubuntu 18.04 or greater, Debian 10 or greater. 
-- The following packages must be installed: 
+- `glibc` 2.27 or newer is required.
+- The following packages must be installed for agent hosting:
 
     - libatomic1 
 
@@ -84,6 +85,8 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
 
     - libgl1 
 
+    - NVIDIA encode runtime library (`libnvidia-encode`)
+
     - libglib2.0-0 
 
 
@@ -96,7 +99,8 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
     :::
 
 #### AlmaLinux 8 or greater, (RHEL)-based. 
-- The following packages must be installed: 
+- `glibc` 2.27 or newer is required.
+- The following packages must be installed for agent hosting:
 
   - libatomic
 
@@ -105,6 +109,8 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
   - vulkan-loader
 
   - mesa-libGL
+
+  - NVIDIA encode runtime library (`libnvidia-encode`)
 
   - glib2
 
@@ -116,4 +122,11 @@ On all platforms an NVIDIA GPU with an installed driver version 535 or greater,
         ```
     :::
 
+:::note Installer behavior
+The Linux installer validates client and agent dependencies separately.
+
+- If `INSTALL_JUICE_POOL` is set, missing agent libraries fail installation.
+- If `INSTALL_JUICE_POOL` is not set, missing agent libraries are reported as warnings because only client binaries are being installed.
+:::
+