Agent Installation Guide#

Audience: End Users, IT Administrators
Prerequisites: Administrator privileges, network access to Kleidia backend
Outcome: Kleidia Agent installed and running on workstations

Overview#

The Kleidia Agent runs on user workstations to enable YubiKey management through your web browser. The agent provides a secure bridge between the browser and locally-connected YubiKey devices.

Current Version: 0.4.6

System Requirements#

Windows#

• Windows 10 (1607+) or Windows 11
• 64-bit (x64) architecture
• Administrator privileges
• Network access to Kleidia backend (HTTPS)

macOS#

• macOS 10.15 (Catalina) or later
• Intel or Apple Silicon
• Administrator privileges
• Network access to Kleidia backend (HTTPS)

IT Administrator: Enterprise Deployment#

Windows - Microsoft Intune#

Upload Package#

1. Sign in to Microsoft Endpoint Manager (https://endpoint.microsoft.com)
2. Navigate to Apps → Windows → Add → Windows app (Win32)
3. Upload kleidia-agent-0.4.6-unsigned.msi
4. Configure application:
   • Name: Kleidia Agent
   • Publisher: Kleidia
   • Install command:

     msiexec /i kleidia-agent-0.4.6-unsigned.msi /qn BACKEND_URL=https://kleidia.example.com

   • Uninstall command:

     msiexec /x kleidia-agent-0.4.6-unsigned.msi /qn

Detection Rule#

Use custom PowerShell script:

$service = Get-Service -Name "KleidiaAgent" -ErrorAction SilentlyContinue
if ($service -and $service.Status -eq "Running") {
    Write-Host "Installed"
    exit 0
}
exit 1

Requirements and Deployment#

1. Requirements: Windows 10 1607+, 64-bit
2. Assignment: Deploy as Required to device groups
3. Notifications: Hide all notifications
4. Monitor: Check device install status in Intune portal

Windows - Group Policy (GPO)#

Prepare Deployment#

1. Create shared folder on domain controller:

   \\DC\Software\Kleidia\

2. Copy installation files:

   • kleidia-agent-0.4.6-unsigned.msi
   • yubikey-manager.msi

3. Create agent.toml configuration in the share:

port = 56123
name = "Kleidia Agent"
backend_url = "https://kleidia.example.com"
allowed_origins = [
    "https://kleidia.example.com"
]

[logging]
level = "info"

4. Create deployment script (deploy-kleidia.ps1):

$ErrorActionPreference = "Stop"

# Install YubiKey Manager dependency
Start-Process msiexec.exe -ArgumentList "/i \\DC\Software\Kleidia\yubikey-manager.msi /qn /norestart" -Wait -NoNewWindow

# Copy configuration
$configDir = "C:\ProgramData\Kleidia\agent"
New-Item -ItemType Directory -Force -Path $configDir | Out-Null
Copy-Item "\\DC\Software\Kleidia\agent.toml" "$configDir\agent.toml" -Force

# Install agent
Start-Process msiexec.exe -ArgumentList "/i \\DC\Software\Kleidia\kleidia-agent-0.4.6-unsigned.msi /qn /norestart" -Wait -NoNewWindow

exit $LASTEXITCODE

Create and Link GPO#

1. Open Group Policy Management Console (gpmc.msc)
2. Create new GPO: “Deploy Kleidia Agent”
3. Right-click and select Edit
4. Navigate to: Computer Configuration → Policies → Windows Settings → Scripts → Startup
5. Click PowerShell Scripts tab → Add
6. Enter script path: \\DC\Software\Kleidia\deploy-kleidia.ps1
7. Click OK to save
8. Link GPO to your Workstations OU
9. On client machines, run gpupdate /force and reboot

macOS - Jamf Pro#

Upload Package#

1. Sign in to Jamf Pro
2. Navigate to Settings → Computer Management → Packages
3. Click New and upload kleidia-agent-0.4.6.pkg
4. Configure:
   • Display Name: Kleidia Agent
   • Category: Productivity
   • Priority: 10

Create Installation Policy#

1. Navigate to Computers → Policies → New

2. General Configuration:

   • Display Name: Install Kleidia Agent
   • Triggers: ☑ Recurring Check-in, ☑ Enrollment Complete
   • Execution Frequency: Once per computer

3. Packages: Add “Kleidia Agent”

4. Files and Processes → Execute Command:

#!/bin/bash
BACKEND_URL="https://kleidia.example.com"
CONFIG_FILE="/etc/kleidia/agent/agent.toml"

# Wait for installation to complete
sleep 10

if [ -f "$CONFIG_FILE" ]; then
    # Update backend URL
    /usr/bin/sed -i '' "s|^backend_url.*|backend_url = \"$BACKEND_URL\"|" "$CONFIG_FILE"
    
    # Update allowed_origins to match backend
    ORIGIN=$(echo "$BACKEND_URL" | /usr/bin/awk -F/ '{print $1"//"$3}')
    /usr/bin/awk -v origin="$ORIGIN" '
        /^allowed_origins/ {
            print "allowed_origins = [";
            print "    \"" origin "\"";
            print "]";
            in_array=1;
            next;
        }
        in_array==1 && /^\]/ { in_array=0; next; }
        in_array==0 { print; }
    ' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
    
    # Restart agent to apply configuration
    /bin/launchctl kickstart -k system/com.kleidia.agent
fi

5. Scope: Select target device groups
6. Click Save

Create Monitoring Extension Attribute#

1. Navigate to Settings → Computer Management → Extension Attributes → New

2. Configuration:

   • Display Name: Kleidia Agent Status
   • Data Type: String

3. Script:

#!/bin/bash
AGENT_BIN="/usr/local/bin/kleidia-agent"
RESULT="Not Installed"

if [ -f "$AGENT_BIN" ]; then
    VERSION=$("$AGENT_BIN" --version 2>/dev/null | grep -o 'v[0-9.]\+' || echo "unknown")
    if /bin/launchctl list | grep -q com.kleidia.agent; then
        RESULT="Installed and Running ($VERSION)"
    else
        RESULT="Installed but Not Running ($VERSION)"
    fi
fi

echo "<result>$RESULT</result>"

4. Click Save

macOS - Microsoft Intune#

Upload Package#

1. Sign in to Microsoft Endpoint Manager (https://endpoint.microsoft.com)
2. Navigate to Apps → macOS → Add → macOS app (PKG)
3. Upload kleidia-agent-0.4.6.pkg
4. Configure:
   • Name: Kleidia Agent
   • Publisher: Kleidia
   • Minimum OS: macOS 10.15

Create Configuration Script#

1. Navigate to Devices → macOS → Shell scripts → Add
2. Name: Configure Kleidia Agent
3. Script Content:

#!/bin/bash
BACKEND_URL="https://kleidia.example.com"
CONFIG_FILE="/etc/kleidia/agent/agent.toml"

# Wait for installation
sleep 10

if [ -f "$CONFIG_FILE" ]; then
    # Update backend URL
    sed -i '' "s|^backend_url.*|backend_url = \"$BACKEND_URL\"|" "$CONFIG_FILE"
    
    # Restart agent
    launchctl kickstart -k system/com.kleidia.agent
fi

exit 0

4. Run as signed-in user: No
5. Hide notifications: Yes
6. Frequency: Once
7. Assign to device groups

Detection Rule#

Custom detection script:

#!/bin/bash
if [ -f "/usr/local/bin/kleidia-agent" ]; then
    if launchctl list | grep -q com.kleidia.agent; then
        echo "Installed"
        exit 0
    fi
fi
exit 1

Verification#

Windows#

# Check service status
Get-Service -Name "KleidiaAgent"

# Check version
& "C:\Program Files\Kleidia\Agent\kleidia-agent.exe" --version

# Test health endpoint
Invoke-WebRequest -Uri "http://127.0.0.1:56123/health"

# View configuration
Get-Content "C:\ProgramData\Kleidia\agent\agent.toml"

macOS#

# Check service status
sudo launchctl list | grep com.kleidia.agent

# Check version
/usr/local/bin/kleidia-agent --version

# Test health endpoint
curl http://127.0.0.1:56123/health

# View configuration
cat /etc/kleidia/agent/agent.toml

Troubleshooting#

Windows#

Service won’t start:

# Check event logs
Get-EventLog -LogName Application -Source "KleidiaAgent" -Newest 20

# Restart service
Restart-Service -Name "KleidiaAgent"

Cannot connect to backend:

# Test connectivity
Test-NetConnection -ComputerName kleidia.example.com -Port 443

# Check backend URL in configuration
Get-Content "C:\ProgramData\Kleidia\agent\agent.toml" | Select-String "backend_url"

macOS#

Service won’t start:

# Check service status
sudo launchctl print system/com.kleidia.agent

# View error logs
tail -50 /var/log/kleidia-agent/stderr.log

# Restart service
sudo launchctl kickstart -k system/com.kleidia.agent

Cannot connect to backend:

# Test connectivity
nc -zv kleidia.example.com 443

# Check backend URL
grep backend_url /etc/kleidia/agent/agent.toml

Configuration Reference#

Configuration File Locations#

Configuration Structure#

Windows:

port = 56123
name = "Kleidia Agent"
backend_url = "https://kleidia.example.com"
allowed_origins = [
    "https://kleidia.example.com"
]

[logging]
level = "info"

macOS:

port = 56123
name = "Kleidia Agent"
backend_url = "https://kleidia.example.com"
allowed_origins = [
    "https://kleidia.example.com"
]

[logging]
level = "info"

Note: Both platforms use the same configuration format. The allowed_origins field is required for CORS security.

Configuration Options#

Important: allowed_origins must include your backend URL for the browser to communicate with the agent.

Security#

Network Requirements#

Outbound (Required):

• Backend server: TCP 443 (HTTPS)

Local Listener:

• 127.0.0.1:56123 (HTTP, localhost only)
• Not accessible from network
• Used by browser to communicate with agent

Service Permissions#

Windows:

• Service runs as Local System
• Configuration: Protected (SYSTEM and Administrators only)

macOS:

• Service runs as root (LaunchDaemon)
• Configuration: root:wheel, mode 0644

Data Security#

• All backend communication over HTTPS (TLS 1.2+)
• JWT tokens are temporary and auto-refresh
• No YubiKey PINs or passwords stored
• Agent only reads YubiKey metadata

Uninstallation#

Windows#

Via Windows Settings:

1. Settings → Apps → Apps & features
2. Find “Kleidia Agent”
3. Click Uninstall

Via Command Line:

$app = Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -eq "Kleidia Agent" }
$app.Uninstall()

macOS#

Using uninstall script:

sudo /usr/local/bin/kleidia-agent-uninstall.sh

Manual removal:

sudo launchctl bootout system/com.kleidia.agent
sudo rm -f /usr/local/bin/kleidia-agent
sudo rm -f /Library/LaunchDaemons/com.kleidia.agent.plist
sudo rm -rf /etc/kleidia/agent

Getting Help#

For IT Administrators#

• Check troubleshooting section above
• Review logs at locations specified above
• For advanced scenarios, see technical reference:
  • Windows: go-agent-http/packaging/windows/ENTERPRISE_DEPLOYMENT.md
  • macOS: go-agent-http/packaging/macos/ENTERPRISE_DEPLOYMENT.md

Version: 0.4.6
Last Updated: 2025-11-10
Platforms: Windows 10+, macOS 10.15+