HandyCafe Docs
it-admin

Getting Started: IT Administrator

This guide covers the technical setup of HandyCafe. By the end, you will have the server and clients installed, network configured, app menus built, and remote management tested.

Time to complete: 5 minutes (plus client deployment time)

Step 1: Install the Server and Clients

Server installation:

  1. Verify your server PC meets the system requirements.
  2. Run the HandyCafe setup on your management PC. On Windows, select Server on the What will this PC be? screen.
  3. Launch the server, sign in with your HandyCafe account and complete the First Setup Wizard. It creates the admin account, sets the admin account for client computers and the connection key, and shows a pairing code.
  4. Note the server PC's local IP address. Clients need it only if pairing with a code and automatic discovery both fail.

Client installation (repeat for each PC):

  1. Run the same setup on each customer-facing PC and select Client. For mass deployment, run it silently with /S /ROLE=client.
  2. The client opens the Connect this computer to your server screen.
  3. Type the six-digit code from the server's Connection Wizard and click Connect. The client receives the connection key automatically.
  4. If a code cannot be used, search the network or enter the server IP address manually.
  5. Once connected, the client appears on the server's Computers page.

Tip: New clients are named automatically with a prefix like "PC #1", "PC #2", etc. Change the prefix or rename PCs in Settings > Clients > Registered Clients. See Registered Clients.

See Server Installation and Client Installation for detailed steps.

Step 2: Configure Network Settings

Navigate to Settings > Clients on the server and select the Network tab.

HandyCafe uses four ports for communication:

Port Default Purpose
TCP Port 5001 Command and response communication
File Port 5002 File transfers between server and clients
Remote Management Port 5003 Remote desktop streaming control
UDP Port 5004 Screen streaming data

Configuration:

  1. Set the TCP Port, File Port and UDP Port under Ports (defaults work for most setups). The remote management port is not shown on this tab.
  2. Set the Connection Key. This is a shared secret used for HMAC-SHA256 authentication. All clients must use the same key. Paired clients receive it automatically. Changing it later disconnects every paired computer until it pairs again.
  3. Click Save.

Firewall rules:

Ensure these ports are open on both the server and client PCs:

  • TCP: 5001, 5002, 5003 (inbound on server, outbound on clients)
  • UDP: 5004 (bidirectional for screen streaming)
  • UDP: 45998 on the server, for pairing clients with a code

Important: All PCs must be on the same local network (subnet). HandyCafe uses mDNS for client discovery, which requires LAN connectivity.

See Network Settings for all network options.

Step 3: Set Up the Client Menu

The client menu is the app launcher that customers see on their desktop. Navigate to Settings > Clients > Content tab.

  1. Create categories. Group apps by type (e.g., Games, Browsers, Social Media, Tools).
  2. Add apps to each category:
    • Set the app name and description.
    • Choose the app kind: Game, Browser, Link, File, or App.
    • Set the executable path or launch URI.
    • Upload an icon and optionally a poster image for the app card.
  3. Reorder categories and apps using drag handles.
  4. Toggle visibility to show or hide items.
  5. Click Save.

Changes are pushed to all connected clients automatically in real time via TCP.

Tip: Use the IGDB integration to search for game metadata and icons automatically.

See Client Menu for the complete menu builder documentation.

Step 4: Configure Idle Screen and Appearance

Idle Screen (Settings > Clients > Idle Screen tab):

The idle screen is what customers see when no session is active (the lock screen).

  1. Choose a Screen Mode: Standard (built-in animation), Media (your own images and videos), Gamer (game artwork showcase) or Mix (rotates between the modes you pick).
  2. For Media, add images or videos and set the duration per item and the transition effect.
  3. Optionally enable a clock overlay and cafe name display with custom colors.
  4. Click Save.

Appearance (Settings > Clients > Appearance tab):

Configure the look of the online desktop that customers use during sessions.

  1. Select a Design Theme.
  2. Configure Background type: solid color, gradient, image, or video with overlay and blur settings.
  3. Adjust Card density (Large, Medium, Compact).
  4. Click Save.

The General tab of the same page sets the Client Display Mode: fullscreen Game Mode or the Desktop Mode side panel. See Client Display Modes.

To lock down Windows tools, drives and browser features on client PCs, use the Restrictions tab. See Client Restrictions.

See Client Idle Screen and Client Appearance for all options.

Step 5: Test Remote Desktop and Screenshots

Verify that remote management works:

Screenshots:

  1. On the Computers page, select any online client card.
  2. Click Screenshot on the client card.
  3. A screenshot of the client's screen appears in the viewer.
  4. You can download or refresh the screenshot.

Remote Desktop:

  1. Select an online client card and click Remote Desktop.
  2. A remote desktop window opens with live H.264 streaming.
  3. You can control the mouse and keyboard on the remote PC.
  4. Clipboard synchronization works between server and client.

Note: Remote desktop uses UDP streaming. If the video is laggy, check your network bandwidth and ensure UDP port 5004 is not blocked. You can also adjust the bitrate in the stream settings (350-25,000 kbps).

See Remote Desktop and Screenshots for all remote features.


Network Architecture Overview

Server PC (Management)
    |
    |--- TCP (5001) --- Command/Response (bincode + HMAC-SHA256)
    |--- TCP (5002) --- File Transfers
    |--- TCP (5003) --- Remote Management Control
    |--- UDP (5004) --- Screen Streaming (H.264)
    |--- UDP (45998) - Pairing with a code
    |--- mDNS ------- Client Discovery (automatic)
    |
    +-- Client PC 1
    +-- Client PC 2
    +-- Client PC 3
    +-- ...

What to Do Next

  • File Sync: Deploy files and configurations to client PCs
  • Software Licenses: Track concurrent software licenses across PCs
  • QR Login: Let members sign in by scanning a code with the HandyCafe app