Skip to content

Devices & Connections

qbee-connect's core purpose is browsing your Qbee device inventory and establishing secure port-forwarding connections to access services on remote devices. This document covers finding devices, creating connections, and managing active tunnels.

Finding Devices

The device table is qbee-connect's main interface, displaying your Qbee.io device inventory with search, filtering, and pagination controls.

Browse the Device Table

After login, the device table displays your devices in a paginated grid.

The table has six columns:

Column Description
Device Device title. Click to select the device.
Online Status icon indicating connectivity: green (online), yellow (delayed), or red (disconnected).
Connection Info Count of active connections to this device, with an info button for details.
Group Hierarchy path showing where the device is organized (e.g., "Building A > Floor 2").
Tags Comma-separated tags assigned to the device in Qbee.io.
Actions Settings icon (⚙) to open the connection dialog, or Cancel icon (×) to disconnect an active connection.

Device Status Indicators

The Online column shows the device's current connectivity status:

Icon Status Description
✓ Online Device is connected to the Qbee platform and reachable
⚠ Delayed Device connection is delayed — may be temporarily unavailable
✕ Disconnected Device is offline or unreachable

Search for a Device

The search bar at the top of the device table supports three search modes.

  1. Click the search mode dropdown to choose a search mode:

    • Device name — Free-text search by device title
    • Group — Search with autocomplete suggestions for device groups
    • Tag — Search with autocomplete suggestions for device tags

  2. Perform the search based on the selected mode:

    • Device name: Type the device name in the search field and press Enter.
    • Group: Begin typing to see autocomplete suggestions, then select a group from the dropdown.
    • Tag: Begin typing to see autocomplete suggestions, then select a tag from the dropdown.

  3. The device table filters to show only matching devices.

  4. Click the Refresh button to clear the search and reload the full device list.

Expected outcome

The device table shows only devices matching your search criteria.

Filter by Active Connections

To view only devices with active tunnels:

  1. In the pagination bar at the bottom of the device table, check the Open tunnels on page checkbox.

  2. The device table filters to show only devices that currently have active port-forwarding connections.

  3. Uncheck the checkbox to return to the full device list.

The pagination controls at the bottom of the device table let you navigate through large device inventories.

  1. Items per page: Click the dropdown to select how many devices to show per page — 10 (default), 25, 50, or 100.

  2. Page navigation: Use the Previous and Next buttons to move between pages. The current position is shown as Page X / Y.

  3. The device table updates immediately when you change page size or navigate.

Creating Connections

Port forwarding maps a port on a remote device to a port on your local machine, creating a secure tunnel through the Qbee platform.

Note

For more on how tunneling works, see What is qbee-connect → How qbee-connect Works.

Connection Workflow

The connection workflow follows these steps:

  1. Select Device — Find the target device in the device table
  2. Choose Service — Select a preset (SSH, HTTP, HTTPS, VNC, RDP) or custom
  3. Configure Ports — Set local and remote ports (presets fill remote port automatically)
  4. Save & Connect — Click to establish the tunnel
  5. Tunnel Active — The connection appears in the active connections list as tcp: localhost:PORT → remote:PORT

Warning

The target device must show an online status (green icon in the Online column) before you can establish a connection.

Open the Connection Dialog

  1. Find your target device in the device table.

  2. Click the Settings icon (⚙) in the Actions column of the device row.

  3. The connection dialog opens. Each row in the dialog represents one port-forwarding target.

Configure Port Forwarding

Each target row contains seven fields:

Field Description
Local Port Port on your machine. Leave blank for automatic assignment.
Local Addr Local address to bind to. Defaults to 127.0.0.1.
Type/Service Service preset dropdown: SSH, HTTP, HTTPS, RDP, VNC, or custom.
Remote Port Port on the remote device. Auto-filled for service presets, editable for custom.
Remote Addr Address on the remote device. Defaults to 127.0.0.1 (the device itself).
Protocol Transport protocol: tcp (default) or udp.
Delete Trash icon button to remove this target row.

Service preset port mappings:

Service Remote Port
SSH 22
HTTP 80
HTTPS 443
RDP 3389
VNC 5900

When you select a service preset, the Remote Port field is automatically filled and disabled. Select custom to enter any port number manually.

To forward multiple ports to the same device, click Add Target to add additional rows.

Start the Connection

  1. After configuring your target rows, click Save & Connect.

  2. The connection dialog closes and the tunnel is established.

  3. The connection appears in the active connections view, showing the local and remote port mapping.

  4. In the device table, the Actions column icon changes from Settings (⚙) to Cancel (×) for the connected device.

Expected outcome

The port-forwarding tunnel is active. You can now connect to the remote service via localhost on the assigned local port.

Connection failed?

If the connection fails to establish, verify that the target device is online (green status icon) and that the remote port is correct for the service you want to access. See Troubleshooting for more help.

Common Connection Scenarios

SSH Access

  1. Select SSH from the Type/Service dropdown. The Remote Port is set to 22 automatically.

  2. Click Save & Connect.

  3. Open a terminal and connect using the assigned local port:

    ssh -p <local-port> user@localhost

    Replace <local-port> with the port number shown in the active connections view and user with your device's SSH username.

Web Interface

  1. Select HTTP or HTTPS from the Type/Service dropdown. The Remote Port is set to 80 or 443 respectively.

  2. Click Save & Connect.

  3. Open your browser and navigate to:

    http://localhost:<local-port>

    For HTTPS services, use https://localhost:<local-port>. If the remote service uses TLS and its certificate is not signed for localhost, your browser will display a certificate warning due to hostname mismatch — this is expected and you can proceed past the warning for internal services.

Database Access

For database services (MySQL, PostgreSQL, MongoDB, etc.):

  1. Select custom from the Type/Service dropdown.

  2. Enter the Remote Port number for your database:

  3. MySQL: 3306
  4. PostgreSQL: 5432

  5. MongoDB: 27017

  6. Select tcp from the Protocol dropdown.

  7. Click Save & Connect.

  8. Connect your database client to localhost:<local-port>.

VNC Remote Desktop

  1. Select VNC from the Type/Service dropdown. The Remote Port is set to 5900 automatically.

  2. Click Save & Connect.

  3. Open your VNC client and connect to localhost:<local-port>.

Custom Service

  1. Select custom from the Type/Service dropdown.

  2. Enter the Remote Port number for your service.

  3. Select tcp or udp from the Protocol dropdown as required by the service.

  4. Click Save & Connect.

Connection Status

View Active Connections

Active connections are shown in a scrollable list.

Each device section displays:

  • Device title as a heading
  • Device ID below the title

  • Tunnel details for each port mapping, formatted as:

    {protocol}: {localHost}:{localPort} → {remoteHost}:{remotePort}

    For example:

    tcp: 127.0.0.1:2222 → 127.0.0.1:22

If you have multiple targets configured for a single device, each mapping appears as a separate line.

Note

When no connections are active, the view displays a "No active connections." message.

Close a Connection

You can close a connection from either the active connections view or the device table.

From the active connections view:

  1. Locate the device section for the connection you want to close.

  2. Click the red Disconnect button next to the device.

  3. All tunnels to that device are terminated.

From the device table:

  1. Find the connected device in the device table (it shows a Cancel icon in the Actions column).

  2. Click the Cancel icon (×) in the Actions column.

  3. All tunnels to that device are terminated.

Expected outcome

The connection is closed. In the device table, the Actions column returns to showing the Settings icon (⚙). The device section is removed from the active connections view.

Verification

Test your connection by accessing the remote service through the local port:

  • SSH: Run ssh -p <local-port> user@localhost and confirm you get a login prompt.
  • HTTP/HTTPS: Open http://localhost:<local-port> in your browser and confirm the page loads.
  • VNC: Connect your VNC client to localhost:<local-port> and confirm the remote desktop appears.
  • Database: Connect your database client to localhost:<local-port> and confirm you can access the database.

Troubleshooting

If you encounter connection issues:

  • Connection refused: Verify the device is online (green status icon) and the remote port is correct
  • Port already in use: The local port is already allocated by another application — either close the conflicting application or choose a different local port
  • Connection drops intermittently: Check the device's connectivity status (yellow icon indicates delayed connection)

For more troubleshooting help, see Troubleshooting.

See Also

Intent Document
Install qbee-connect and connect to your first device Getting Started
Understand how tunneling works Overview → How qbee-connect Works
Log in to qbee-connect Managing the Application → Authentication
Switch between accounts Managing the Application → Authentication
Use the system tray Managing the Application → System Tray
Troubleshoot a connection issue Troubleshooting