--- title: Installation slug: yqFB-installation docTags: createdAt: 2025-08-11T11:13:48.000Z --- Install a remote agent on a Docker or Podman host by copying the install script from Turbine and running it on the target machine. ## Choose Your Path | **I want to…** | **Start here** | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Install with Docker or standard Podman | [Install a Remote Agent](./#install-a-remote-agent) | | Install with Podman Quadlet (systemd lifecycle) | [Use Podman Quadlet](./#use-podman-quadlet) | | Pull connector images from my own registry | [Pull Connector Images from an Override Registry](./#pull-connector-images-from-an-override-registry) | | Review install fields and flags | [Configuration Options](./#configuration-options) | ## Install a Remote Agent 1. Open **Admin Panel** > **Settings** > **Tenant** > **Nodes**. 2. Click **View Agents** to see your agents and pools. ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/ELATYAGcPedcZ33Cvor-Z_adminpanel.png" size="70" width="1595" height="683" darkWidth="1595" darkHeight="683" position="center" showCaption="false"} 3. Open the **Install an agent** dialog. 4. Fill in the required fields. See [Configuration Options](./#configuration-options). 5. Click **Copy Install Script**. 6. Paste the script into a terminal on the target host and run it as a user that can start containers (and systemd, if you use Quadlet). 7. Complete any prompts. The script can ask for Turbine credentials; credentials are not saved. :::hint{type="info"} Do not click outside the install dialog before you copy the script. Closing the dialog resets the generated command. ::: Sample install command pattern: ```bash curl -k https:///agent/install.sh | bash -s -- -n 'my_agent' -S '0 */4 * * *' ``` ## Configuration Options | **UI field or flag** | **Description** | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **AGENT\_NAME** (`-n`) | Required. Letters, numbers, hyphen, or underscore only. Do not use spaces. | | **CA\_CERT\_PATH** (`-c`) | Folder of CA certificates for self-signed or internal TLS validation. | | **AGENT\_INITIAL\_POOLS** (`-o`) | Comma-delimited pools to join at install time. You can add more than one. | | **AGENT\_CONTAINER\_NETWORK\_SUBNET** (`-N`) | Container network subnet in CIDR format. Default: `10.55.55.0/24`. | | **HTTP\_PROXY** / **HTTPS\_PROXY** / **NO\_PROXY** | Proxy settings for outbound agent traffic. Wildcards are not supported in **NO\_PROXY**. | | **CRON\_SCHEDULE** (`-S`) | Cron expression for automatic agent image updates. | | **Ignore Insecure Certificates** | Instructs the agent and its connectors to ignore insecure certificates when connecting to HTTPS sources. | | **Allow Insecure Certificates for Gateway Communication** | Allows an insecure certificate when connecting to the Turbine agent gateway. | | **Use Podman Quadlet** (`-Q`) | See [Use Podman Quadlet](./#use-podman-quadlet). Podman only. Available in Turbine 26.3.0. | | `-B` / `-C` | Override registries for Swimlane and custom connector images. Script-only. See [Pull Connector Images from an Override Registry](./#pull-connector-images-from-an-override-registry). Available in Turbine 26.3.0. | :::hint{type="info"} Additional options may be available only on the command line. Run the install script with help for the full usage list. ::: ## Use Podman Quadlet Starting in **Turbine 26.3.0**, the **Install an agent** dialog includes **Use Podman Quadlet**. When enabled, the generated install command adds the `-Q` flag so the agent runs as a systemd Quadlet for OS-integrated lifecycle management. | **Requirement** | **Detail** | | ----------------- | ---------------------------------------------------------------------------------- | | Container runtime | Podman only. The install script validates that Podman is present when `-Q` is set. | | Podman version | Podman 4.4 or later. Recommended platforms: RHEL 9 or Rocky Linux 9. | | UI toggle | **Use Podman Quadlet** β€” hint text in the product matches this requirement. | | Script flag | `-Q` β€” Use Podman Quadlets for managing agent containers. | ### Enable Quadlet from the UI 1. Open the **Install an agent** dialog. 2. Complete required fields such as **AGENT\_NAME**. 3. Turn on **Use Podman Quadlet**. 4. Click **Copy Install Script**. 5. Run the script on a Podman 4.4+ host. ### Enable Quadlet from the Script Add `-Q` when you install or reinstall with Podman: ```bash # Example fragment β€” include your full -t, -n, and other required flags bash -s -- -t '' -n 'my_agent' -Q -S '0 */4 * * *' ``` :::hint{type="info"} For Docker-based hosts, leave **Use Podman Quadlet** off. Quadlet is a Podman and systemd integration. ::: :::hint{type="info"} Quadlet unit files live under `/etc/containers/quadlets/` for root and under `{HOME}/.config/containers/systemd` for non-root. After you change Quadlet files manually, run `systemctl daemon-reload`. ::: ## Pull Connector Images from an Override Registry Starting in **Turbine 26.3.0**, remote agents can pull connector images from an override registry or namespace instead of only through the agent gateway. This supports environments that must run self-hosted or pre-scanned images. Use these install script flags (add them to the install command manually; they are not toggles on the **Install an agent** dialog): | **Flag** | **Description** | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-B` | Override registry and namespace for **Swimlane** connector images. The agent pulls those images directly from the override location instead of through the agent gateway. | | `-C` | Override registry and namespace for **custom** connector images. Same direct-pull behavior for non-Swimlane connector images. | Example pattern: ```bash bash -s -- -t '' -n 'my_agent' \ -B 'registry.example.com/swimlane-connectors/' \ -C 'registry.example.com/custom-connectors/' ``` The install script sets agent environment variables such as `CONTAINER_IMAGE_PATH_SWIMLANE` and `CONTAINER_IMAGE_PATH_CUSTOM` from `-B` and `-C`. ## Preflight Checks During installation, the script runs several checks. Watch for warnings or errors. Warnings or errors may not block installation, but they can affect stability or performance. Checks performed: - Primary Swimlane Turbine system connection - Login credentials - Image access from [Quay.io](https://quay.io/) (or other image repositories you provide) - CGroup v2 enablement - Container host version, function, and storage size - Ability of the container host to run an image - Quality of connection to the Turbine environment (including latency) - Virtual container network settings - Conflicting containers or networks on the container host ::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/d5_tEd4Shyc10Yn7cheFg_agent-preflight.png" size="70" width="837" height="611" darkWidth="837" darkHeight="611" position="center" showCaption="false"} ## Related Guides - [Remote Agents](https://docs.swimlane.com/remote-agents) - [Viewing Remote Agents](https://docs.swimlane.com/viewing-remote-agents) - [Uninstall Remote Agent](https://docs.swimlane.com/uninstall-remote-agent)