> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/install-a-connector.md). # Install a Connector Install and run the Roboflow Video Connector on macOS, Linux, Windows, or Docker. The Roboflow Video Connector connects cameras on your computer or local network to Cloud Streaming. Run it on a machine that can reach the cameras and stay online while they are in use. Model inference runs in Roboflow's cloud, not in the connector. After installation, [connect a source](/deployment/roboflow-cloud/cloud-streaming/connect-a-source.md). ## Before you start You need a workspace API key, access to the camera's network, and permission to capture and send its video. Open "Deployments" → "Cloud Streaming" → "Add Video Source" → "Connect a Camera" for the setup command and connection status. The dialog has a tab for macOS, Linux, and Windows, and opens on the tab for your computer. You can also find your workspace key in "Settings" → "API Keys". Do not paste keys into chat, source control, or screenshots. Native archives cover macOS and Linux on x86-64 and ARM64, and Windows on x86-64. Linux requires glibc 2.28 or later and the system GnuTLS runtime: `libgnutls30` or its distribution successor on Debian/Ubuntu, or `gnutls` on RHEL-compatible distributions. The connector includes FFmpeg; a native Linux archive is not dependency-free. USB discovery is available on supported macOS and Linux camera interfaces. Windows installation does not add USB camera discovery; use a network camera there. Linux discovery covers USB V4L2 capture interfaces, not CSI, virtual, or proprietary industrial camera interfaces. ## CLI ### Install on macOS or Linux Run the public installer: ```sh curl --proto =https --proto-redir =https -fsSL https://repo.roboflow.com/rfv-connector/latest/install.sh | sh ~/.rfv-connector/rfv-connector --version ``` The installer detects your operating system and architecture, then checks the selected release's checksums before installing. The executable is `~/.rfv-connector/rfv-connector`; `~/.rfv-connector` alone is a directory. The installer does not add the executable to your PATH. To use the shorter command in your current terminal: ```sh export PATH="$HOME/.rfv-connector:$PATH" rfv-connector --version ``` For future terminals, add that export once to your shell's startup file, such as `~/.zshrc` or `~/.bashrc`. If you set a custom `RFV_INSTALL_DIR`, add its absolute path instead. An EU download mirror is also available: ```sh curl --proto =https --proto-redir =https -fsSL https://repo.roboflow.eu/rfv-connector/latest/install.sh | RFV_DOWNLOAD_BASE=https://repo.roboflow.eu/rfv-connector sh ``` This changes where installation files download from. It does not select a processing region or change the API endpoint. ### Install on Windows In PowerShell, run the installer, then check the version: ```powershell irm https://repo.roboflow.com/rfv-connector/latest/install.ps1 | iex & "$env:USERPROFILE\.rfv-connector\current\rfv-connector.exe" --version ``` You can also click "Download Installer" on the "Windows" tab of the setup dialog to get `roboflow-connector.bat`. Double-click it. It asks for your workspace API key and starts the connector. It does not save the key to disk. To install from the ZIP archive instead: 1. Select a version from the public [release version pointer](https://repo.roboflow.com/rfv-connector/latest/LATEST_VERSION.txt). 2. Download `rfv-connector_windows_amd64.zip` and `checksums.txt` from the same versioned directory, `https://repo.roboflow.com/rfv-connector//`. Use the pointer's version including its `v` prefix (ex: `v0.10.0`). 3. In PowerShell, calculate the archive's checksum: ```powershell Get-FileHash .\rfv-connector_windows_amd64.zip -Algorithm SHA256 ``` 4. Compare it with the exact ZIP filename's SHA256 in `checksums.txt`. Do not run the archive if the checksum is missing or different. 5. Extract the whole archive to a permanent folder. Keep `ffmpeg.exe`, source files, and notices with the executable. Native releases are unsigned. A verified browser download can trigger macOS Gatekeeper or Windows SmartScreen. Follow your organization's software policy; use an administrator-approved installation if required. If your policy allows a verified unsigned release, macOS can offer "System Settings" → "Privacy & Security" → "Open Anyway", and Windows SmartScreen can offer "More info" → "Run anyway". Do not disable system security checks globally. A checksum verifies the downloaded release bytes, not code signing or notarization. ### Start and configure the connector Set the workspace key in `ROBOFLOW_API_KEY` through your normal local secret-management process, then start the connector: ```sh ~/.rfv-connector/rfv-connector --api-url https://api.roboflow.com --api-key "$ROBOFLOW_API_KEY" ``` On Windows, in PowerShell: ```powershell & "$env:USERPROFILE\.rfv-connector\current\rfv-connector.exe" --api-url https://api.roboflow.com --api-key "$env:ROBOFLOW_API_KEY" ``` If you installed from the ZIP archive, run `.\rfv-connector.exe` from the extracted folder instead. Allow camera access for the application or terminal that launches the connector when your OS asks. On Linux, the launching user must be allowed to read the camera's capture device. Use your system's device-access policy rather than making all devices writable. Return to the setup dialog and check that the connector is connected. If a connector was already online, the dialog confirms when a new camera from it appears. Its cameras then appear in the source list. Continue with [source setup](/deployment/roboflow-cloud/cloud-streaming/connect-a-source.md).
Connector setup dialog with its API key redacted and a successful connection.

Run the connector and wait for the connection confirmation.

### Keep it running The native command stays in the foreground. Closing its terminal, stopping the process, sleeping the machine, or losing the network can interrupt its sources. Installation alone does not install a background service. For unattended operation, use an administrator-managed OS service or Docker, and keep the machine awake. Do not launch another copy to recover an existing installation. Check its status and restart the existing process. Stop its cloud jobs before planned maintenance and verify the intended source after restart. ## Docker Use an immutable release tag or digest, not a mutable tag. This example pins `0.10.0` and keeps the configuration and installation identity in a named volume: ```sh docker run -d --name rfv-connector \ --restart unless-stopped \ -v rfv-connector-state:/state \ repo.roboflow.com/rfv-connector:0.10.0 \ --api-url https://api.roboflow.com \ --api-key "$ROBOFLOW_API_KEY" ``` Set `ROBOFLOW_API_KEY` through your normal secret-management process before running the command. Return to "Deployments" → "Cloud Streaming" to confirm the connector is connected and [add cameras](/deployment/roboflow-cloud/cloud-streaming/connect-a-source.md#rtsp-and-onvif-cameras). In bridge networking, ONVIF multicast discovery cannot see the camera LAN; add a known RTSP URL through the platform. Use a native connector when you need LAN discovery. For Linux USB cameras, expose the required capture devices, such as `--device /dev/video0`, and ensure the container can read their sysfs identity. Docker on macOS does not automatically expose the host's webcam. Use the native connector when you need that camera. Keep `/state` on persistent storage. Mount the directory, not just `connector.json`. Do not give simultaneous installations the same state volume. ## Preserve state when updating The installation directory contains the binaries. The data directory separately holds configuration and identity:
InstallationDefault data directory
macOS~/Library/Application Support/rf-video-connector
Linux$XDG_STATE_HOME/rf-video-connector, or ~/.local/state/rf-video-connector
Windows%LOCALAPPDATA%/rf-video-connector
Docker/state
`--data-dir` overrides `RFV_DATA_DIR` and the default. `--config` can point at a separate configuration file. Back up both the entire data directory and any separate configuration, keeping the backup private because it may contain keys and camera passwords. 1. Stop the cloud jobs and the old connector before an upgrade. 2. Preserve its data directory, installation identity, and storage mounts. For older containers, confirm where both config and identity are stored before replacing them; a legacy config mount alone may not include identity. 3. Rerun the native installer, extract a verified Windows release, or select a new immutable Docker version. Do not overwrite or discard persistent state. 4. Start one connector and confirm the expected cameras and installation are still recognized. For containers, verify persistence after replacement, not only after a restart. For an older Linux installation with `usb:videoN` source IDs, verify camera-to-Workflow bindings before upgrading. New hardware-based IDs must not be assigned to old cameras by guessing their current device number. Keep a backup and review the migration with your administrator before resuming processing. To remove an installation, first stop its jobs and process or service. Remove its cloud connector registration only when no longer needed, then remove the installed binaries. Delete local state only if you intend to lose its identity and saved settings; reinstalling without that state creates a new installation. ## Network requirements The connector opens outbound connections to the Roboflow API and the media destination assigned to it. You do not need to forward an inbound internet port to the camera. Its machine still needs local access to the camera's RTSP or ONVIF service, and outbound media access in addition to HTTPS API access. ONVIF discovery uses local multicast, which may not cross VLANs or container bridges. On restricted networks, have your network administrator validate the assigned media endpoint and allowed transports. Do not expose camera ports to bypass a firewall. If the connector is online but the camera or video is missing, see [troubleshooting](/deployment/roboflow-cloud/cloud-streaming/troubleshooting.md).