Server setup and operations

Everyday commands

koyd doctor
koyd start --open
koyd open
koyd status
koyd instances
koyd logs
koyd pair
koyd stop INSTANCE_ID
koyd help COMMAND

start runs Koyd in the background, so you can close the terminal. serve keeps it in the foreground for troubleshooting or a service manager. Neither one starts Koyd again after a reboot.

koyd instances lists every server registered for your account. Copy the full ID to target one with status, open, logs, or stop. status shows the address, data folder, and latest log file. stop ends active agents, terminals, and browser sessions, and keeps saved work and paired devices.

Run koyd help for the overview, and koyd help COMMAND or koyd COMMAND --help for one command. Help works even when saved settings are broken. koyd version shows the installed version.

A friendly local address

Installation sets up https://koyd.internal:4319 after you approve the Windows permission prompt, or enter your administrator password on Mac or Linux. Koyd registers the local name and trusts its own HTTPS certificate, so you don't edit system files or run certificate commands. Port 4319 stays clear of 443 and 8443, which development servers often use.

If you cancelled the prompt or need to repair the address, run koyd setup and approve the prompt. Installed files and saved work are kept.

koyd setup

The address works only on that computer. For other devices on your network, see Connect over Wi-Fi below. For access from anywhere, see Access outside your local network. To go back to direct local access, run koyd address disable and restart Koyd.

Good to know · If another program already uses port 4319, or koyd.internal already points somewhere else, setup explains the conflict and leaves the existing service alone. On Linux, Koyd installs missing certificate tools where it can and configures Chromium and existing Firefox profiles. Restart your browser if it still shows a certificate warning. Managed browsers may need their administrator.

Save configuration

Installation saves one config file that every koyd command uses, from any folder. koyd setup repairs the local address and keeps your other settings. For your own proxy or a service manager, koyd setup --no-address creates only the config file. Run koyd help config to see every option.

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

Settings include name, host, port, dataDir, publicUrl, clientUrl, and origins. Command-line options override saved settings. Restart Koyd after a change. Don't put provider keys in this file; add providers in Settings → Providers.

Company computers and networks

The irm ... | iex command runs a downloaded script right away. If your company reviews software first, download https://koyd.app/install.ps1 in your browser, read it or pass it to IT, then run it from the download folder in PowerShell. Add --no-address to skip the hostname and certificate changes, and --no-path to leave your PATH alone.

.\install.ps1

The script is not Authenticode-signed, so a policy that requires a signed publisher will stop it. Ask IT for an approved deployment instead of changing the execution policy or turning off security tools.

The installer and background server trust your system's certificates and use the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables by default. Settings you made yourself, such as NODE_USE_SYSTEM_CA or NODE_EXTRA_CA_CERTS, are kept, and TLS verification stays on. Requests to the local server skip the proxy. Proxy auto-configuration (PAC or WPAD) and integrated proxy sign-in are not detected, so ask IT for an explicit proxy setting if you need one.

Pair devices

Each browser or installed app pairs once with each server. On a device that is already connected, open Settings → Instances → Get a browser link. On the server computer, koyd pair prints a link, and koyd open opens the workspace with a fresh one.

Links work once and expire after five minutes. When the server hosts its own app, which is the normal setup, you also get an 8-character code such as K7F9-QMX2. Open the server's address on the new device and type the code under Pairing code or link instead of copying the link. Using the code or the link uses up both. After 10 wrong codes from anyone, Koyd cancels every active code; links stay valid.

When you pair, name the browser or app you are using, like Chrome on work laptop. That name appears in the server's access list. Access renews automatically while a device is in use, for 90 days at a time. A device left unused for about 90 days, cleared browser storage, a different browser, or removed access needs a fresh pairing. A stalled connection retries with the saved access instead of asking you to pair again.

Review and remove access

Settings → Instances lists your servers under Your servers, and marks the one you are using as In use. Choose Manage saved access to see the server hosting the projects, this browser or app (marked You are here), and Other saved connections.

Choose Remove access next to another browser or app to revoke it immediately. These entries are saved pairings, not computers on your network, so one computer can appear several times. To remove this browser's own access, use the disconnect button next to the server in Your servers. On the server computer, use koyd devices.

koyd devices
koyd devices revoke DEVICE_ID

Good to know · Pair only devices you trust. A paired device has full owner access to that server's projects, files, agents, and terminals; there are no guest or read-only roles. Revoking a device blocks its next requests but does not undo work it already started.

Connect over Wi-Fi

Connect a phone, tablet, laptop, or desktop on the same trusted network without a public tunnel. Sharing is off by default and works with the normal koyd.internal setup. The other device needs only a browser.

1. On the server computer, open Settings → Instances → Get a browser link. Choose the Wi-Fi or Ethernet network shared with the other device. To keep sharing on after restarts, check Keep sharing after restarts and updates.
2. Choose Enable sharing on this network. Koyd prepares its HTTPS proxy and certificate and checks the connection.
3. Choose Create setup link. Scan the QR code with a phone or tablet, or open the link on another computer. On the setup page, choose Download certificate and follow the steps for that device. iPhone and iPad get a configuration profile; other devices get a certificate file.
4. After approving trust, select This device trusts the certificate, keep the browser option selected, and choose Open Koyd in this browser. Choose Connect instance, then bookmark the Browser address for later.

To add a laptop's server to the Koyd app you already use on your desktop, create a setup link on the laptop and paste it into Settings → Instances → Add another computer on the desktop. If this is the first connection to that laptop, choose Open certificate setup, approve its certificate, and return to connect. On the setup page, Add to my existing Koyd app gives you a pairing link to paste instead. If a device already trusts this server's certificate, Create pairing link skips certificate setup.

The setup page needs internet access on both devices. Without it, expand Offline setup / manual certificate transfer, send the certificate to the other device yourself, approve trust there, then create a pairing link and open or scan it on that device. To check the file, compare the SHA-256 fingerprint under Verify the certificate before you approve trust.

Good to know · Trust only the certificate from your own server, because a trusted certificate authority can vouch for any website. The certificate stays the same across sharing sessions, so each device approves it once. Setup and pairing links work once and expire after five minutes; create a fresh one if certificate setup takes longer.

Sharing, restarts, and connection help

Without Keep sharing after restarts and updates, sharing stops when the server restarts, and you enable it again on the server computer. With it, Koyd saves the network and address and restores sharing after restarts and updates once that exact address is available again. Koyd still has to be running; the option does not start it at sign-in. Turn sharing off closes network access and clears the option. Pairings and certificate trust stay either way.

Koyd stops sharing if the selected network's address, subnet, or hardware changes, and never follows a new address on its own. Reserve the server's address in your router to keep bookmarks working. Koyd cannot tell Wi-Fi networks apart by name, so turn sharing off before moving to an untrusted network. Sharing supports private IPv4 networks only.

• Use the same network on both devices. Guest networks, client isolation, or a VPN can block the connection. Router port forwarding is not needed.
• The default HTTPS port is 8443. Change it under Address options if another program uses it.
• On Windows, Connection help → Allow through Windows Firewall… asks for approval to add one rule for this proxy, address, port, and subnet on the Private profile. It does not change your network profile.
• On Mac or Linux, allow the HTTPS proxy and port in your firewall if needed. Managed devices may need their administrator.
• For a certificate error, finish the trust steps on that device and restart its browser. Don't click past the warning.
• Leave sharing off on a server that already has a public HTTPS address.

Use koyd.internal on other devices

The setup QR code uses the server's IP address, so it works without router changes. To use a name instead, check Also accept koyd.internal under Address options, add a local DNS record on your router that points koyd.internal to the server's address, and reserve that address in DHCP. Each device still trusts the certificate once.

With the default port, the address is https://koyd.internal:8443. Port 443 removes the port from the address if it is free; Mac and Linux may require permission to use it. The hosts entry on the server computer does not reach phones, and devices with custom, encrypted, or VPN DNS may ignore your router's record.

Access outside your local network

For access from anywhere, give the server a public HTTPS address with your own domain and a reverse proxy, or a tunnel you trust. Keep Koyd listening on loopback port 4317 and publish only the proxy. The proxy must keep the Host header, forward WebSockets, and refuse the /api/local path, which is only for commands on the server itself.

koyd.example.com {
    @local path /api/local /api/local/*
    respond @local 404
    reverse_proxy 127.0.0.1:4317
}

This Caddy example obtains and renews its certificate once your domain's DNS points at the server. Install Koyd with --no-address, save the public address, and run koyd serve under a service manager so the server survives reboots. Then run koyd pair on the server.

koyd setup --no-address --name "VPS" --public-url https://koyd.example.com
koyd pair

On the new device, open https://koyd.example.com, enter the code that koyd pair printed, and choose Connect instance. Later, on any connected device, Settings → Instances → Get a browser link → Create one-time code and link gives you a new code and QR code.

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

Good to know · Visitors who know the domain see only the sign-in screen and the instance name, version, and readiness. Treat codes and links like passwords. Publish only SSH and HTTPS, use SSH keys, and don't give the account that runs Koyd administrator rights. Anyone with a shell on the server can create pairing codes.

Connect several instances

One Koyd app can hold several servers. Choose Settings → Instances → Add another computer and paste the other server's setup or pairing link. Each server keeps its own projects, agents, identity, access, and live updates, and stopping one leaves the others connected. Your workspace across devices explains switching and side-by-side windows.

Each additional server needs a reachable HTTPS address and must allow the app's exact origin, for example with --origin https://koyd.internal:4319 or an entry in the config's origins array. Pairing is still required. koyd.internal always means the computer where it was set up, so a server on another computer needs its own address.

Good to know · Only one managed local proxy can use port 4319. A second instance on the same computer needs its own data folder, backend port, and HTTPS port. A different hostname alone does not avoid the conflict.

For a second local instance, run these commands from an existing folder with ports 4318 and 8443 free. Approve its address setup, then paste the pairing link that start prints into Settings → Instances → Add another computer in your original app.

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

The second server answers at https://second.internal:8443. You keep using https://koyd.internal:4319 and switch between servers there.

Service managers and portable packages

To start Koyd at boot, run koyd serve under your own service manager with the same config. Background mode alone does not survive a reboot or sign-out. Service-managed servers update manually; see Updating Koyd.

An extracted release package, such as one you build from source, runs without installation through koyd-server.cmd on Windows or sh ./koyd-server.sh on Mac and Linux. The installed koyd command adds the friendly local address and updates from the app.

Backups and moving a server

Stop the server before you back it up, then copy its data folder and config together, plus any project folders you need. koyd status shows the data folder. A copy of a running server's data is not a consistent backup, and resource exports are not complete server backups.

To move to another computer, install Koyd there, restore the data folder and config while both servers are stopped, and start exactly one server with that data. The bundled runtime matches its operating system and processor, so install the release for the new machine instead of copying program files. Never run two servers from the same data folder.

Good to know · Keep backups private. Server data contains provider credentials, device pairings, and the private key of the local HTTPS certificate.

Remove Koyd

Run koyd uninstall. It asks whether to keep your data, and Keep my data is the default: a later reinstall in the same place reconnects to the same server identity, settings, saved work, and paired devices. It then shows the application and data locations and asks you to confirm. Deleting data permanently requires typing DELETE.

koyd uninstall
koyd uninstall --keep-data --yes
koyd uninstall --remove-data --yes

Scripts must pass --yes and exactly one data option. Project folders outside the data folder and other instances are kept. Installed browser apps, browser storage, and shared certificate trust belong to your browser and system settings; remove them there if you no longer need them.

When something does not connect

• Run koyd doctor, koyd status, and koyd logs on the server computer.
• Check that the computer is awake and the right instance is running. koyd instances lists them all.
• If Settings → Instances shows Pair again, this device's access expired or was removed. Pair it with a fresh code or link.
• If a code or link expired or was already used, create a new one. Each works once, for five minutes.
• Check the HTTPS address, allowed origins, and WebSocket forwarding of any proxy you configured.
• A port that is already in use stops startup with an error. Choose a free port with --port, or stop the other instance.