Self-Hosting

Connect Clients

Connect desktop, mobile, and web clients to your self-hosted Kokomo server.

Your Server URL

All Kokomo clients need your server URL to connect. This is the domain or IP address where your server is running.

Your server URL:

https://kokomo.yourdomain.com

Desktop Apps (macOS, Windows, Linux)

Connection Steps:

1
Download the app
Get the native app for your platform from the Downloads page or your admin.
2
Open the app and select "Self-Hosted Server"
On the login screen, tap the server icon or "Use Custom Server".
3
Enter your server URL
Enter https://kokomo.yourdomain.com
4
Sign in with your credentials
Use the account created by your administrator or sign up if allowed.

macOS: Set default server via command line

# Set custom server URL
defaults write io.macroblink.kokomo serverURL "https://kokomo.yourdomain.com"

# Verify
defaults read io.macroblink.kokomo serverURL

Mobile Apps (iOS, Android)

Connection Steps:

1
Download from App Store / Play Store
Search for "Kokomo" or use the link from your admin.
2
Tap "Self-Hosted" on welcome screen
Or tap the gear icon in the top right corner.
3
Enter server URL or scan QR code
Your admin can generate a QR code from the admin panel.

Tip: Generate a QR code for easy mobile setup at https://your-server/admin/qr-code

Web Client

Access Kokomo directly in your browser without installing anything.

Simply open your server URL in a modern browser:

https://kokomo.yourdomain.com

Supported browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+

Enterprise Deployment

Pre-configure the server URL for managed devices.

macOS MDM Configuration Profile

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>io.macroblink.kokomo</string>
            <key>serverURL</key>
            <string>https://kokomo.yourdomain.com</string>
            <key>enforceServer</key>
            <true/>
        </dict>
    </array>
</dict>
</plist>

Windows Registry (GPO)

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Macroblink\Kokomo]
"ServerURL"="https://kokomo.yourdomain.com"
"EnforceServer"=dword:00000001

Troubleshooting

"Connection Failed" Error

• Verify the server URL includes https://
• Check that SSL is properly configured
• Ensure ports 443 is open on your firewall

"Certificate Error"

• Verify your SSL certificate is valid and not expired
• Ensure the certificate matches your domain
• For self-signed certs, install the CA on client devices

Messages not syncing

• Check WebSocket connection in browser dev tools
• Verify Redis is running: docker compose ps redis
• Check server logs: docker compose logs kokomo-server

SSL & Domain Maintenance