HandyCafe Docs
it-admin

How to Configure Network Settings

This guide covers the network configuration required for HandyCafe Server and clients to communicate. You will learn how to change server ports, set up connection keys for authentication, configure Windows Firewall, troubleshoot connectivity problems, and handle multi-VLAN setups.

How to Change Server Ports

HandyCafe uses several ports for different types of communication. The defaults work for most setups. Change them only if there is a conflict with another application.

What you will need

  • HandyCafe Server running with admin access.
  • Knowledge of which ports are already in use on your network (use netstat -an to check).
  • The ability to restart the HandyCafe Server after making changes.

Steps

  1. Open the HandyCafe Server application and navigate to Settings in the left sidebar.
  2. Select the Network tab.
  3. Locate the TCP Port field. The default is 5001. Change it to your desired port number. This port handles the primary command and response communication between server and clients.
  4. Locate the File Transfer Port and UDP Port fields. Change these if needed. The file transfer port handles asset syncing (icons, images). The UDP port handles screen streaming for remote desktop.
  5. Click Save to apply the new port configuration.
  6. Restart the HandyCafe Server application for the port changes to take effect.
  7. Update the port configuration on every HandyCafe Client to match the new server ports. Each client must be configured to connect on the same ports the server is listening on.

Expected result

After restarting, the server listens on the new ports. Clients configured with the matching ports connect successfully.

Common mistakes

  • Changing the server port without updating the clients. Clients will fail to connect because they are still trying to reach the old port.
  • Choosing a port that is already in use by another service. The server will fail to bind and will not start. Check with netstat -an | findstr :5001 (replacing 5001 with your chosen port) before committing to a port number.
  • Forgetting to restart the server. Port changes do not take effect until the server process restarts.

How to Set Up the Connection Key

The connection key is a shared secret that authenticates communication between the server and clients. Every TCP message is authenticated using HMAC-SHA256 with this key. Without a matching key, clients cannot connect.

What you will need

  • HandyCafe Server running.
  • Access to all client PCs to update their configuration.

Steps

  1. Navigate to Settings > Network in the HandyCafe Server application.
  2. Locate the Connection Key field.
  3. Enter a strong shared secret. Use a mix of letters, numbers, and symbols. The key should be at least 16 characters long. For example: hC!2026$NetCafe#Secure.
  4. Click Save.
  5. On each HandyCafe Client PC, open the client settings and enter the exact same connection key. The key must match character for character, including capitalization and special characters.

Expected result

All clients with the matching key connect successfully. Any device without the correct key is rejected by the server. This prevents unauthorized machines from joining your network.

Common mistakes

  • Typing the key differently on the server and a client. Even one character difference causes authentication failure. Copy and paste the key to avoid typos.
  • Using a very short or simple key like "1234" or "password." While the system accepts any string, a weak key provides little security.
  • Forgetting to update one or two client PCs after changing the key. Those clients will show as disconnected until their key is updated.

How to Configure Windows Firewall

Windows Firewall blocks incoming connections by default. You must create rules to allow HandyCafe traffic.

What you will need

  • Administrator access on the server PC.
  • The port numbers your HandyCafe Server uses (default: TCP 5001, 5002, 5003 and UDP 5004).

Steps

  1. Open Windows Firewall with Advanced Security. Press Win+R, type wf.msc, and press Enter.
  2. In the left panel, click Inbound Rules.
  3. In the right panel, click New Rule.
  4. Select Port as the rule type and click Next.
  5. Select TCP, enter 5001 in the specific local ports field, and click Next. Select Allow the connection and click Next. Check all profiles (Domain, Private, Public) and click Next. Name the rule "HandyCafe TCP 5001" and click Finish.
  6. Repeat steps 3 through 5 for TCP port 5002 (file transfer) and TCP port 5003. Create each as a separate rule with a descriptive name.
  7. Create one more rule. This time select UDP instead of TCP, enter 5004 for the port, and follow the same steps. Name it "HandyCafe UDP 5004."
  8. Verify all four rules appear in the Inbound Rules list and show a green checkmark indicating they are enabled.

Expected result

Windows Firewall allows incoming connections on all HandyCafe ports. Client PCs can now reach the server through the firewall.

Common mistakes

  • Creating outbound rules instead of inbound rules. The server needs inbound rules to accept connections from clients. Outbound connections are typically allowed by default.
  • Forgetting the UDP rule. Without it, remote desktop streaming will not work even though command communication (TCP) functions normally.
  • Selecting only the "Domain" profile. If your network is classified as Private or Public by Windows, the rule will not apply. Check all three profiles to be safe.

How to Troubleshoot Client Connectivity

Follow this systematic process when a client cannot connect to the server.

What you will need

  • Access to both the server PC and the affected client PC.
  • A command prompt or terminal on both machines.

Steps

  1. Verify the server is running. On the server PC, confirm that the HandyCafe Server application is open and the main page shows the Admin Panel. If the server is not running, start it.

  2. Ping the server from the client. On the client PC, open a command prompt and run ping [server-ip] (replace with your server's actual IP address). If the ping fails, the problem is at the network layer. Check cables, switches, and IP configuration. The client and server must be on the same network or have a route between them.

  3. Check that the server ports are listening. On the server PC, open a command prompt and run netstat -an | findstr :5001 (replace 5001 with your configured TCP port). You should see a line showing LISTENING on that port. If not, the server failed to bind to the port. Check for port conflicts.

  4. Check firewall rules. On the server PC, verify that the Windows Firewall rules from the section above are present and enabled. Temporarily disabling the firewall (then re-enabling) can confirm whether the firewall is the issue.

  5. Verify the connection key matches. On the client PC, open the HandyCafe Client settings and confirm the connection key is identical to the one on the server. A mismatched key causes the client to appear as if it cannot connect at all. The server rejects the authentication silently.

  6. Check mDNS discovery. HandyCafe clients use mDNS to automatically find the server on the local network. If mDNS is blocked (some managed networks disable multicast), the client cannot discover the server automatically. In this case, enter the server IP address manually in the client configuration.

Expected result

By following these steps in order, you isolate the problem to a specific layer: network, port, firewall, authentication, or discovery. Most connectivity issues are resolved at step 2 (network) or step 4 (firewall).

Common mistakes

  • Skipping step 1. If the server application is not running, nothing else matters.
  • Assuming the firewall is not the problem because "it was working yesterday." Windows updates sometimes reset firewall rules or reclassify the network profile.

How to Set Up HandyCafe Across VLANs

In larger networks, servers and clients may be on different VLANs (virtual local area networks). Since mDNS broadcasts do not cross VLAN boundaries, automatic discovery will not work.

What you will need

  • The server's static IP address.
  • Routing configured between VLANs on your network switch or router.
  • Firewall rules allowing HandyCafe traffic between VLANs.

Steps

  1. Assign a static IP address to the HandyCafe Server PC. DHCP-assigned addresses can change, breaking client configurations. Configure the static IP through Windows Network Settings or your DHCP server's reservation feature.

  2. On each HandyCafe Client, open the client configuration and enter the server IP address manually instead of relying on automatic discovery.

  3. Enter the correct TCP port and connection key in each client's configuration.

  4. On the network router or layer-3 switch, ensure that traffic on the HandyCafe ports (TCP 5001-5003, UDP 5004 by default) is allowed to route between the server VLAN and the client VLAN.

  5. Test connectivity from a client on the remote VLAN by pinging the server IP. Then verify that the HandyCafe Client connects and appears in the server's Admin Panel.

Expected result

Client PCs on different VLANs connect to the server using the manually configured IP address. All features work as they do on a single-subnet network.

Common mistakes

  • Using DHCP for the server without a reservation. If the server IP changes, every client loses its connection.
  • Forgetting to allow UDP traffic between VLANs. TCP connections may work (commands succeed) while UDP traffic is blocked (remote desktop streaming fails).
  • Not accounting for inter-VLAN firewall rules on managed switches. Enterprise switches often block inter-VLAN traffic by default.