Skip to content
KoydDownload free

Server setup and operations

Install and run your own Koyd instance, pair trusted devices, and configure remote access.

Everyday commands

Command
koyd doctor
koyd start --open
koyd open
koyd status
koyd instances
koyd logs
koyd pair
koyd stop INSTANCE_ID

start launches a background process you can leave running after the terminal closes. serve runs in the foreground for debugging or a service manager. Background mode alone does not arrange startup after reboot.

A friendly local address

The installer sets up https://koyd.internal automatically. Approve the Windows permission prompt or enter your administrator password on Mac or Linux. Koyd registers the local name and trusts its HTTPS certificate for you. No port, system-file edits, certificate commands, or separate enable step are needed.

  1. Run the install command for your system.
  2. Approve the system permission prompt for Koyd's local address.
  3. Open a new terminal and run koyd start --open. Close the terminal after startup finishes.
  4. Choose Connect instance in the browser. Return to https://koyd.internal whenever Koyd is running.

If you cancel the permission prompt or need to repair setup, run the following command and approve the prompt. Your installed files and workspace remain available.

Command
koyd setup

Koyd manages the local HTTPS proxy with the server and keeps the app running under your regular account. The default address is local to that computer. For another device on your network, use Connect over Wi-Fi below. For access outside your network, configure a reachable HTTPS proxy or tunnel. Start Koyd again after a reboot.

Good to know · If another application occupies HTTPS port 443 or the hostname already points elsewhere, setup explains the conflict and preserves the existing service or mapping. On supported Linux distributions, missing certificate tools are installed automatically and Koyd configures Chromium and existing Firefox certificate stores. Restart the browser if needed; managed or protected stores may require their administrator. Advanced deployments can use install --no-address and configure their own proxy.

Save configuration

Normal installation saves the configuration and local address automatically. koyd setup repairs the local address while preserving other settings. Installed commands use a stable config outside their release folders. For an external proxy or service-managed deployment, use koyd setup --no-address to create only the configuration file.

Command
koyd setup --no-address --config "/path/to/koyd.config.json"
koyd start --config "/path/to/koyd.config.json"

Supported settings include name, host, port, dataDir, publicUrl, clientUrl, origins, and custom resource paths. Normal installed builds do not need custom core, UI, or resource paths.

Pair devices

Use koyd pair, koyd open, or Manage devices → Pair another device to create a pairing link. Links work once and expire after five minutes. The server grants a device credential after successful pairing; that credential is stored in the browser’s application database.

Good to know · Pair only devices you trust. Paired devices belong to the instance owner and have full control; this is not a scoped team-sharing or multi-tenant service. Revoke lost devices through Manage devices.

Connect over Wi-Fi

Connect any device on the same trusted network — a phone, tablet, laptop, or desktop computer — without opening a public tunnel. Sharing is off by default and works with the normal loopback server and local koyd.internal setup.

  1. On the server computer, open Manage devices → Connect over Wi-Fi. Select the Wi-Fi or Ethernet connection shared with your other device.
  2. Choose Enable sharing on this network. Koyd prepares its HTTPS proxy and certificate, then checks the local connection.
  3. Choose Set up another device. Scan the QR code with a phone or tablet, or open the setup link on another computer. On the HTTPS setup page, choose Download certificate and follow the trust instructions. iPhone and iPad receive a certificate profile; other devices receive a certificate file.
  4. After approving trust, select This device trusts the certificate, then Connect to Koyd. Choose Connect instance in the app.

Easy setup requires internet access on both devices. Koyd checks setup-page availability before creating the QR code. If it is unavailable, expand Offline setup / manual certificate transfer, send the public certificate directly to your device, approve trust, and generate the offline pairing QR code.

Good to know · Trust only the certificate from your own server. A paired device has full control of that instance. Pairing links work once and expire in five minutes; generate a fresh link if certificate setup takes longer. Certificate trust is retained across sharing sessions. Separate browser or PWA storage may require pairing again.

Sharing, restarts, and connection help

Keep the server computer awake. Turn sharing off closes the network connection while the local workspace keeps running. Server shutdown, update, or restart also turns sharing off. Re-enable it on the server computer afterward; device pairings and certificate trust are retained.

Koyd stops sharing if the selected interface’s address, subnet, or hardware identity changes. It does not identify Wi-Fi by its network name; turn sharing off before moving to an untrusted network. Automatic sharing currently supports private IPv4 networks.

  • Use the same network on both devices. Guest-network isolation or a VPN can prevent connections; router port forwarding is not needed.
  • The default HTTPS port is 8443. Change it under Address options if another program uses that port.
  • On Windows, Connection help → Allow through Windows Firewall… requests system approval for a rule limited to the selected private network, address, proxy, and port. It does not change your network profile.
  • On Mac or Linux, allow the HTTPS proxy and port in your firewall if needed. Managed device policies may require administrator help.
  • For certificate errors, finish the device’s trust instructions and restart its browser. Create a fresh QR code if pairing has expired.

Use koyd.internal on other devices

The IP-address QR code works without router DNS changes. To use a friendly name, enable Also accept koyd.internal under Address options and add a local DNS record on your router pointing koyd.internal to the server’s selected network address. Reserve that address in DHCP and trust the instance’s certificate on each device.

The default address is https://koyd.internal:8443. Choosing port 443 removes the port from the address, if that port is available; low ports may need OS permission on Mac or Linux. Koyd does not replace an existing listener. The computer’s local hosts entry alone cannot publish the name to phones, and custom or VPN DNS may bypass your router’s record.

Access outside your local network

Local use can run on a loopback address. Remote clients need a reachable HTTPS origin through a reverse proxy or tunnel you configure. Keep the server listener on loopback behind a local proxy when possible. Forward HTTP and WebSocket traffic and configure the matching public URL.

Command
koyd serve --public-url https://koyd.example.com

If the PWA is hosted on a different origin, explicitly allow that client origin with --origin or clientUrl. A plain LAN address is not enough for a secure PWA context. localhost on a phone means the phone, not your server.

Connect several instances

The UI at https://koyd.internal can connect to several Koyd instances. Choose Add instance and paste another server's full pairing link. Every connection keeps its own server identity, device credential and live updates. Stopping one server leaves the others connected.

Each additional server needs a reachable HTTPS endpoint. Allow the UI's exact origin on that server with --origin https://koyd.internal, or include it in the config's origins array. Pairing is still required. A server on another computer needs its own HTTPS address; koyd.internal refers to the computer where setup registered it.

Good to know · Only one managed local proxy can use port 443. A second instance on the same computer needs a separate data directory, backend port and HTTPS port. A different hostname alone does not avoid a port conflict. The main UI can keep its port-free address while connecting to that second endpoint.

For a second local instance, run these commands from an existing directory with ports 4318 and 8443 available. Approve its address setup, then paste the pairing link printed by start into Add instance in your original UI.

Command
koyd setup --no-address --config ./second.config.json --data-dir ./second-data --name "Second workspace" --port 4318 --origin https://koyd.internal
koyd address setup --config ./second.config.json --hostname second.internal --https-port 8443
koyd start --config ./second.config.json

The second server uses https://second.internal:8443. You can continue opening https://koyd.internal and switch instances there.

Portable and service-managed use

An extracted package can run through koyd-server.cmd on Windows or sh ./koyd-server.sh on macOS/Linux. The per-user installer provides the koyd command, friendly local address, and automatic updates. Install the PWA through your browser for an app icon.

Use koyd serve under your chosen service manager when you need boot-time startup. Update these deployments with a complete matching package and restart through that manager; Koyd does not take over its restart policy.

Backups and migration

Back up the server data directory and config while the instance is stopped, along with any project files you need. Resource exports are not complete server backups. Keep backups private because server data can contain provider credentials and device pairings.

When something does not connect

  • Run koyd doctor, koyd status, and koyd logs on the server.
  • Check that the machine is awake and the correct instance is running.
  • Verify the HTTPS address, allowed origin, and WebSocket proxy configuration.
  • Create a fresh pairing link if the previous one expired or was used.
  • Use koyd instances to identify a conflicting port or an already-running instance.