Skip to content
LabTether

Connectors

Connectors let LabTether discover and monitor infrastructure you already run — Proxmox clusters, TrueNAS storage, Docker hosts, Portainer environments, PBS backup servers, and Home Assistant instances — without installing an agent on each one. You point LabTether at an API, and it pulls in assets, telemetry, and status on a schedule.

How connectors work

A connector is an API integration between LabTether and an external platform. Once configured, it:

  • Discovers assets — VMs, containers, storage pools, backup jobs, smart-home entities — and adds them to your inventory with source metadata.
  • Collects telemetry — CPU, memory, disk, temperature, and platform-specific metrics flow into the same pipeline as agent-reported data.
  • Syncs on a schedule — each connector polls at a configurable interval, so your inventory stays current without manual refresh.

Agents vs. connectors: Agents give you deep control — terminal, desktop, file browsing, service discovery. Connectors give you visibility into platforms that expose an API but do not run your code. Many setups use both: a Proxmox connector discovers your VMs, and agents installed inside those VMs provide interactive access.

Onboarding order: Start with one connector, validate it end-to-end, then expand. A sensible order for a typical homelab:

  1. Proxmox (primary compute)
  2. TrueNAS (storage and SMART health)
  3. Docker or Portainer (container workloads)
  4. PBS and Home Assistant (backup and smart-home context)

You do not need all connectors configured — start with whichever covers your highest-value infrastructure.

Tip: Track connector health and sync freshness regularly. Treat repeated auth errors as priority incidents — they usually mean a token expired or permissions changed upstream.

A sync can finish with a partial outcome. That means the platform API was reachable, but the inventory was incomplete or only partially persisted. Read the warning before assuming the connector is broken — LabTether isolates the issue to that connector run rather than treating it as a global outage. Prefer fixing visibility or ACL issues upstream before deleting and recreating the connector.

Permissions

Use dedicated service accounts or API tokens per connector. Never reuse your personal admin credentials for daily sync.

Connector Minimum scope Avoid
Proxmox Read inventory, VM metadata, task status; scoped console/session rights if needed Full root token for daily sync
TrueNAS Read system/storage metrics and event/task access Full admin key for routine telemetry
Docker Read container/host state; action scope only if you need start/stop Unrestricted daemon admin
Portainer Environment read + endpoint inventory; scoped action rights as needed Global admin token for all environments
PBS Read datastore/task/backup metadata Full control token when read-only suffices
Home Assistant Read entity/state/service metadata Owner-level token unless you specifically need it

Recipe:

  1. Create a dedicated integration identity in the upstream system.
  2. Grant read-only permissions first.
  3. Test the connector in LabTether.
  4. Add action privileges only when a specific workflow requires them.
  5. Rotate the token on a schedule and after any incident.

Proxmox

What it discovers: Proxmox nodes, QEMU VMs, LXC containers, task status, and RRD-based telemetry (CPU, memory, disk I/O).

Setup:

  1. In your Proxmox datacenter, create an API token for a dedicated user with read permissions across the cluster.
  2. In LabTether, open Connectors and add a Proxmox connector.
  3. Enter the API URL (e.g., https://pve.local:8006) and paste the token.
  4. Run Test Connection to verify auth and reachability.
  5. Save and trigger the initial sync.
  6. Check Nodes and Topology — your Proxmox hosts and guests should appear with source metadata.

Tip: If discovery seems incomplete, verify your API token has visibility across all cluster nodes. A token scoped to a single node will only discover assets on that node.

Desktop access: LabTether defaults Proxmox QEMU VMs to VNC for browser sessions, since not every VM exposes a SPICE port. If you know a VM has a SPICE-capable display adapter, you can switch to the SPICE protocol in the desktop view. See Remote Desktop for protocol details.

TrueNAS

What it discovers: System health, storage pools, datasets, SMART data, and event/task metadata.

Setup:

  1. In TrueNAS, generate an API key for a dedicated user with read permissions.
  2. In LabTether, add a TrueNAS connector.
  3. Enter the endpoint URL (e.g., https://truenas.local/api/v2.0) and the API key.
  4. Test, save, and sync.
  5. Verify storage assets and health telemetry appear in the console.

Warning: If telemetry stops updating, check the polling interval and the TrueNAS API key expiration first. Stale data is usually a credentials or network issue rather than a LabTether bug.

Docker

What it discovers: Docker hosts, containers, images, networks, volumes, and runtime state. Container metrics (CPU, memory, block I/O, PIDs) feed into the same telemetry pipeline and are available via Prometheus export.

Setup:

  1. Expose the Docker daemon API or use a socket proxy. The agent on a Docker host can also handle discovery — see the services page for agent-based Docker discovery.
  2. In LabTether, add a Docker connector.
  3. Configure the endpoint and access method.
  4. Test and sync.
  5. Verify containers appear in Services and Nodes.

Tip: If you are running an agent on the Docker host already, agent-based Docker discovery may be a better fit than a standalone connector. The connector is most useful when you want to monitor Docker hosts that do not have an agent installed.

Portainer

What it discovers: Portainer environments, endpoints, containers, and stacks. Device pages show the cluster name you entered during setup instead of Portainer's default label (like local). Container and stack detail pages show Portainer-specific metadata — image, ports, stack membership, entry point, and linked endpoint host.

Setup:

  1. In Portainer, generate an API key. You only need the key secret — the Token ID label is optional for a friendly identifier in LabTether.
  2. In LabTether, add a Portainer connector.
  3. Enter the Portainer URL and API key.
  4. Test and sync.
  5. Verify that Portainer-backed resources appear in inventory and services views, and that device detail pages show a dedicated Portainer panel.

Tip: If the test passes but sync fails with endpoint discovery errors, the API key can likely reach Portainer but cannot list environments. Check the key's permissions in Portainer.

Proxmox Backup Server

What it discovers: Datastores, backup jobs, task history, and storage capacity. PBS metrics (labtether_pbs_datastore_*, labtether_pbs_backup_count, etc.) are exported via Prometheus.

Setup:

  1. In PBS, create an API token with datastore and task read access.
  2. In LabTether, add a PBS connector.
  3. Enter the URL and credentials.
  4. Test and sync.
  5. Verify backup data appears in the UI.

Tip: If no data returns despite a passing test, verify that backups and tasks actually exist in the datastores visible to your token.

Home Assistant

LabTether's Home Assistant integration works in two directions:

LabTether reads Home Assistant (the connector) — pulls entity state, service metadata, and device context into LabTether so you can correlate smart-home signals with infrastructure.

Home Assistant reads LabTether (the custom integration) — exposes LabTether devices, sensors, and actions inside Home Assistant for automations, dashboards, and entity tracking.

Setting up the LabTether connector (LabTether side)

  1. In LabTether, add a Home Assistant connector.
  2. Enter the Home Assistant URL and a long-lived access token.
  3. Test and sync.
  4. The Devices page now shows the Home Assistant hub as its own card. Open it to see the connector URL, entity counts, and domain breakdown in the Home Assistant panel.
  5. Synced entities appear under Services, grouped by hub. Each entity's detail page shows its HA state, entity ID, timestamps, and metadata.

Setting up the custom integration (Home Assistant side)

Tested against Home Assistant Core 2026.3.1.

  1. Copy or symlink custom_components/labtether from the labtether-homeassistant repository into your Home Assistant custom_components/ directory.
  2. Restart Home Assistant.
  3. Go to Settings → Devices & Services → Add Integration and search for LabTether.
  4. Enter your hub URL, an API key, and an optional display name.
  5. Only enable Ignore TLS certificate errors if the hub uses a self-signed cert you trust.
  6. Choose what to import: status entities, telemetry sensors, power switches, the labtether.run_action service, and polling interval.
  7. Finish setup.

After setup, use Configure on the integration entry to adjust imports, polling, and TLS settings. If the API key expires, Home Assistant prompts for reauthentication instead of requiring a remove/re-add cycle.

Multiple LabTether hubs can coexist in the same Home Assistant instance without identifier collisions. Newly discovered LabTether assets appear automatically without an integration reload.

Home Assistant add-on (experimental)

LabTether can also run as a Home Assistant add-on. This is experimental — it runs the hub binary directly inside HA, with support for external or bundled local Postgres. See Settings → Add-ons → Add-on Store and add the LabTether add-on repository URL. Configure labtether_owner_token, labtether_admin_password, encryption_key, and optionally database_url and tls_mode. Auto-generated credentials are written to /data/labtether-addon/generated-credentials.txt.

Warning: The add-on path is experimental. For production homelabs, running LabTether as a standalone Docker stack with a connector to Home Assistant gives you more control over upgrades and resource isolation.