start with kern-cli doctor — it checks the endpoint file, connectivity, api version, and registry in one shot.

windows: "windows protected your pc" — smart screen, because the installer isn't os-code-signed. *more info → run anyway*. updates afterwards are minisign-signed and verified before install.

macos: "kern can't be opened" — gatekeeper, same reason. right-click the app → *open* once. no intel build yet; apple silicon only.

linux: appimage won't launch — chmod +x kern_*.AppImage then run it. fuse is needed: install libfuse2 on debian/ubuntu if the appimage complains.

the cli found no running app:

1. 1.is kern running? kern-cli doctor names the path it looked in.
2. 2.is the automation api enabled? settings → automation & cli — it's on by default (port 7442).
3. 3.are you in the same user session? the app data dir is per-user; sudo kern-cli won't find your config.
4. 4.using a portable/dev setup? point KERN_APP_DATA_DIR at the directory that holds automation.json.

usually a stale endpoint file from a crashed instance, or a port clash:

• ·kern-cli doctor shows the endpoint's pid and start time. compare with the actual process.
• ·kern-cli endpoint --format json prints the url the cli is using.
• ·restart kern — it rewrites automation.json (keeping the token).
• ·if two kern instances run on one machine, only the first binds 7442; the second logs [automation] failed to bind. give one a different automationPort.

the token in the endpoint file doesn't match the running app. restart the app, or delete automation.json and restart to re-mint. if you use KERN_AUTOMATION_TOKEN, check for a stale value in your shell profile.

run kern-cli preflight "<name>". the usual suspects:

that's the graceful window expiring. kern sent the stop command (stdin or the plugin's stop step), waited, then force-killed the process tree. if it's always forced:

• ·the server ignores its stop command — check the instance's stopCommand.
• ·the world save genuinely takes that long — raise stopTimeoutSecs on the instance.
• ·it's a custom instance with stopCommand: "" — the stdin step is deliberately skipped; kern waits the full timeout then kills. set a stop command if the process supports one.

the folder is missing (moved, renamed, external drive unplugged). kern keeps the record instead of deleting it. re-point the instance at the folder via edit, or remove the record. nothing is deleted automatically, ever.

1. 1.same network? guest wi-fi often isolates clients.
2. 2.the app binds 0.0.0.0:<port> only while enabled — check settings.
3. 3.windows firewall: allow the private-network prompt; if you dismissed it, add an inbound rule for the port.
4. 4.https warning is expected (self-signed cert) — accept it once.
5. 5.if you changed webRemotePort, re-scan the qr (the url embeds the port).

• ·the log file is <instance>/latest.log; a server that has never produced output has none.
• ·kern appends stdout/stderr to it while running, so a stopped-and-cleared folder reads empty.
• ·kern-cli logs "<name>" --lines 20 shows the tail without the ui.

the dialog names the reason. common ones:

• ·unknown permission — the manifest requests a permission this kern version doesn't know; update kern or the plugin.
• ·kernCompat — the plugin requires a newer host version.
• ·checksum mismatch — the downloaded .kern changed in transit; re-download.
• ·path traversal — the archive contains entries that escape the plugin directory; refuse it and tell the author.

see plugin security.

sysinfo computes process cpu as a delta between samples. the first reading after a launch is meaningless (often 100% for host, ~0% for the new process) and corrects within a second or two. it is not your server.

the full-screen dashboard needs a real terminal. if it garbles, check TERM, try windows terminal, or use the plain commands (kern-cli top --once, kern-cli list) which never use the alternate screen.

the downloaded artifact didn't verify against the embedded public key. this is the updater protecting you. retry; if it persists, download the installer fresh from the releases page. never disable signature checks.

github issues. include kern-cli doctor output, your os, and the exact command or click path.