Connector setup

PrerequisitesCopy Anchor Link

• A Linux amd64 or arm64 server with root access.
• systemd 247 or later, curl, and sha256sum.
• A local HTTP or HTTPS service.
• Outbound HTTPS access to the dashboard host, plus UDP or TCP port 443 to waf-ingress.loclix.network.

The installed connector runs without root privileges and needs no public inbound port.

Connector creationCopy Anchor Link

1. Open Tunnels in your account.
2. Select Add tunnel.
3. Enter a server name.
4. Select Create tunnel.

This opens Install connector. You can reopen it beside the connection map.

InstallationCopy Anchor Link

1. Copy the Install command.
2. Run it on your Linux server.
3. Select Continue to activation.

Use the command supplied by your dashboard. The installer downloads the matching binary and installs the systemd service. Installation alone does not activate the connector.

UDP buffersCopy Anchor Link

From release 0.19.0, the installer sets the host's UDP receive and send buffer limits to at least 7,500,000 bytes, preserving higher values. It saves net.core.rmem_max and net.core.wmem_max in /etc/sysctl.d/90-loclix-connector.conf for restarts.

If installation warns that it cannot change these settings, configure them on the host running your container. Smaller buffers can limit QUIC throughput, but do not prevent a connection. Other sysctl files applied later at boot can override these values.

On an existing server, run the current installation command once to apply the buffer settings and install the restart command. This preserves tokens, connector instances, and update preferences. Automatic connector updates do not change these host settings.

Connector restartCopy Anchor Link

To restart the installed connector:

sudo loclix-connector restart

If several connectors are installed, the command asks you to select one. For a script, select an instance explicitly or restart all of them:

sudo loclix-connector restart --instance ACCOUNT-ID.TUNNEL-ID
sudo loclix-connector restart --all

The selection list uses service names from the original local setup, which may differ from later dashboard changes. Restarting interrupts active requests and WebSockets.

ActivationCopy Anchor Link

1. Enter a Service name, such as web.
2. Enter its Local address, such as http://127.0.0.1:8080.
3. Select Add service for any additional applications.
4. Select Generate activation command.
5. Copy the Activation command and run it on the same server.

The command contains a single-use code valid for ten minutes. Keep it private. Generating a replacement invalidates the previous unused code.

Activation saves the configuration and credential, then starts the connector. Activating an existing connector replaces its token and disconnects replicas using the old token. See credentials and replicas before doing this on a running service.

Each connector supports up to 64 uniquely named services. For example, a generated command can contain:

--service 'web=http://127.0.0.1:8080' --service 'api=http://127.0.0.1:3000'

These are command options, not a standalone command. Use the complete command from setup.

Connectors from release 0.19.0 report their service addresses to your dashboard. Use Edit tunnel to change them after activation; see Local services.

If you reopen activation, enter addresses again to generate a replacement command. Activation adds or replaces the mappings you supply. Removing a row from that form does not remove a service already saved on the server.

Connection statusCopy Anchor Link

Check the tunnel card in Connection map. It refreshes about every five seconds, so a new connection may take a moment to appear.

The connector can connect before you publish a website. Visitors can use a new hostname only after its DNS and certificate setup is complete.

To check the service on your server, replace the IDs below with those from your configuration:

sudo systemctl status loclix-connector@ACCOUNT-ID.TUNNEL-ID.service
sudo journalctl -u loclix-connector@ACCOUNT-ID.TUNNEL-ID.service

PublicationCopy Anchor Link

Follow Published routes to connect a new hostname or an existing website path to your service. Adding a route does not require another activation command.

Local trafficCopy Anchor Link

The connection from your connector to Loclix is encrypted. For the final connection to your application, use an HTTP or HTTPS local address. HTTPS requires a trusted certificate for that address's hostname.

The connector preserves the public Host header, request path, and query string. Configure your application to accept the published hostname.

FailuresCopy Anchor Link

If the activation code has expired or was already used, generate a new command. If activation succeeds but the server cannot save its files, fix the file error and generate a new command.

See Tunnel troubleshooting for connection and service errors.

Manual configurationCopy Anchor Link

You can also start the connector with --config and --token-file. The configuration contains control, account_id, tunnel_id, and a services map. Each service address must be an HTTP or HTTPS origin without a path, query, fragment, or embedded credentials. Dashboard-managed destinations take precedence over this local service map, including after restarts.

Store configuration and token files with mode 0600. Installed services keep them under /etc/loclix-connector/ACCOUNT-ID.TUNNEL-ID/.

Use the Tunnel API for manual credential management. Automatic updates are enabled by default; see Connector updates to change that preference.