Devices, static clients, managed connections, and VPN addresses

A device in Qarvix is a member of a managed network. It could be a router running the agent, a hub, a static WireGuard client, or another node that needs secure access.

This section explains how member types differ, how one-time connection tokens are used, what a VPN IP means, and why the online status of a managed device and a static client is determined differently.

In short

• A managed device runs the Qarvix agent and holds a WSS management channel.
• A static client uses a WireGuard profile with no agent.
• The VPN IP is issued from the selected network's range.
• A connection token is for a device's initial registration and shouldn't be reused.
• A managed device's online status is tied to the agent and WireGuard state.
• A static client's online status is determined by the freshness of its WireGuard handshake.
• Model, firmware, and agent version help with maintenance and diagnostics.

Member types

Not every device at a site needs to be its own Qarvix member. Often it's enough to connect the router and open the LAN subnet or specific API you need through it.

Managed device

A managed device is a router or edge node with the Qarvix agent installed. The list of models that already have a ready-made agent build is in Supported hardware.

The agent handles several jobs:

• connects to the control plane over WSS;
• receives the network configuration;
• configures WireGuard;
• sends heartbeats and diagnostic data;
• applies routes, if the device is used as a gateway;
• reports model, firmware, agent version, and other details, if available.

This scenario fits sites with no public IP, behind carrier NAT, on a regular SIM card, or where inbound ports can't be opened.

Static client

A static client is a network member with no Qarvix agent. It's usually an engineer's laptop, a phone, a workstation, or a server running a regular WireGuard client.

Details:

• no WSS management channel;
• no agent heartbeat;
• the private key stays on the client;
• status is determined by the WireGuard handshake;
• the configuration should be stored securely;
• if a key is compromised, use "Rotate key and generate config" on the device page - the VPN IP, history, and group membership are preserved, only the key pair changes.

A static client is handy for personal engineer access, temporary contractor access, and connecting service servers.

Hub

The hub is the central WireGuard node of a Qarvix network. In the technical diagram, it's not a separate box at a site - it's an interface and logic living on the control plane side.

The hub is responsible for:

• accepting WireGuard connections;
• storing peer state;
• handshake statistics;
• routing between members;
• applying AllowedIPs, ACL, and routes;
• determining the freshness of static clients.

In everyday operation, you don't need to configure the hub manually. It matters for understanding why a static client can be online with no agent, and why its state is evaluated differently than a managed router's.

VPN address

The VPN IP is a member's address inside the Qarvix network. It's issued from the CIDR range of the selected network.

Example:

Network: home-net
CIDR: 10.100.0.0/24
Device VPN IP: 10.100.0.4
Client VPN IP: 10.100.0.8

The VPN IP is needed for:

• reaching the member itself;
• routing between peers;
• ACL rules;
• reachability diagnostics;
• reports and logs;
• connectivity to LAN subnets behind gateway devices.

Before creating a production network, check that the VPN range doesn't overlap with sites' local networks or corporate VPNs.

One-time connection tokens

A connection token is used for a managed device's initial registration.

What matters:

• the token should be single-use;
• the token should have a limited expiry;
• the token binds the device to the selected organization and network;
• the token shouldn't be posted in shared chats;
• once used, the token is considered compromised for reuse;
• if it expires or the connection fails, create a new token.

The token is only needed at the connection stage. After registration, the device should operate on its own credentials and keys.

Managed connections

A managed connection is convenient because the engineer on site doesn't configure WireGuard by hand.

The typical process:

1. The administrator selects a network in Qarvix.
2. Creates a connection token.
3. Hands the token to the engineer or enters it during agent installation.
4. The agent connects to the control plane over WSS.
5. Qarvix issues the WireGuard configuration.
6. The device gets a VPN IP.
7. The administrator checks status, logs, and reachability.

This matters especially for sites behind a mobile carrier: no public IP is needed, and there's no need to ask the carrier to set up port forwarding.

Online and Offline

Statuses need to be read with the member's type in mind.

Managed device

For a managed device, what matters is:

• the agent's WSS session;
• heartbeat;
• WireGuard state;
• time of last contact;
• the result of applying configuration.

If WSS drops, the device may stop receiving commands and updates. If WireGuard doesn't come up, user traffic won't flow even if the agent managed to reach the control plane.

Static client

A static client has no agent and no heartbeat. So its online status is determined by the freshness of the WireGuard handshake at the hub.

This means:

• a client can look offline if it hasn't sent traffic in a while;
• that's not always an error;
• to check, you can trigger traffic from the client;
• if the handshake is fresh, the WireGuard link was active recently.

Device data

For managed devices, it's useful to store and display:

• device name;
• network;
• VPN IP;
• model;
• manufacturer;
• firmware version;
• agent version;
• time of last connection;
• device role: a regular peer, gateway, exit node;
• the agent's available capabilities.

This data helps you understand which devices need updating, which models are in use, and where to start looking when there's a support request.

Devices behind the router

Cameras, PLCs, sensors, POS terminals, meters, and local APIs often don't run WireGuard directly. They stay on the LAN behind the router, and Qarvix opens access to them through a route.

Example:

Site router: 10.100.0.4
LAN behind router: 192.168.10.0/24
Camera: 192.168.10.20
PLC: 192.168.10.30
Meter API: 192.168.10.50:8080

In this case, the router is the Qarvix member, and local devices are reachable through a subnet route and access rules.

When to create a separate static client

Create a static client if:

• a user needs personal VPN access;
• a server needs to reach devices over the tunnel;
• a phone or laptop needs to connect with no agent;
• a contractor needs temporary access;
• an integration runs from an external network and isn't behind a managed router.

Don't use one static profile for several people. If the profile ends up in the wrong place, it becomes hard to tell who actually connected.

When you need a managed router

A managed router is needed when:

• the site is behind NAT or a regular SIM card;
• you need to open a LAN subnet behind the router;
• you need to manage routing centrally;
• you need device state and agent version;
• you need to connect cameras, PLCs, sensors, or an API at the site;
• it matters to apply configuration without manually setting up WireGuard on every device.

This is the primary option for industry, retail, remote sites, and service maintenance.

Checks after adding

After adding a device or client, check:

• the correct organization;
• the correct network;
• the correct VPN IP;
• online/offline status;
• freshness of Last seen;
• an event in the audit log;
• connection events in the device log;
• no conflicts between VPN addresses and subnets;
• whether routes and ACL, if needed, were applied.

Common issues

Device doesn't show up in the list

Check the token, its expiry, the device's access to the control plane, DNS, TLS, and any network restrictions at the site.

Device shows up, but offline

Check the agent's WSS connection, device logs, access to the server, the device's clock, and possible blocking by the carrier or a firewall.

Device online, but no LAN access

Check the subnet route, local subnet, firewall on the router, ACL, peer mesh, and any overlap in address ranges.

Static client offline

If the client hasn't sent traffic in a while, this can be a normal state. Trigger traffic from the client and check the freshness of the handshake.

VPN IP conflicts with a local network

Choose a different CIDR for the Qarvix network or change the site's local addressing. It's best to fix subnet overlaps before a production launch.

Checklist

• The device or client is in the right organization.
• The device was added to the right network.
• The VPN IP was issued from the expected range.
• The managed device holds both WSS and WireGuard.
• The static client has its own profile.
• Connection tokens aren't reused.
• Model, firmware, and agent version are shown, if available.
• A subnet route is configured for LAN access.
• ACL doesn't open extra destinations.
• The logs show connection and configuration-change events.

Related sections

• Quick device onboarding - the practical scenario for adding a device or client.
• First steps in Qarvix - the general first-launch route.
• Networks, routes, and ACL - connectivity and routing rules.
• Device API over the tunnel - access to local services behind the router.
• Diagnostics and common issues - what to check for connection errors.