Troubleshooting
ruk is not found
Confirm the global package-manager binary directory or standalone executable is on PATH, then run:
ruk --versionThe npm package installs a native platform binary. Node.js or Bun may be needed by the package manager during installation, and the published command entry may briefly run Node to finish native placement when install scripts were skipped, but neither remains the command supervisor afterward.
The declared package manager is missing
Ruk uses the repository's packageManager field before lockfile detection. Install that manager at the declared version or configure a deterministic installCommand.
Status says sync-required
The dependency fingerprint changed, the recorded projection is missing or was modified (including a linked package target), or the workspace has not been prepared.
ruk sync --jsonAcquisition fails on a branch
Git rejects a local branch that is already checked out in another worktree. Inspect active worktrees:
git worktree list
ruk list --jsonChoose another agent branch or release the worktree that owns it.
Release reports a dirty workspace
Normal release protects uncommitted work. Commit, export, or discard the files, then retry with the same assignment ID.
Forced release discards work
ruk release <assignment-id> --force resets and cleans the worktree, including ignored files. Use it only when losing those files is acceptable.
An assignment expired
Expiry does not remove ownership. If the agent is still active, renew the exact assignment ID. If it has stopped, preview garbage collection and confirm the recovery target before using --force-expired.
ruk update reports an untrusted release pagination link
Ruk 0.4.1 through 0.5.0 cannot read GitHub's release list now that it spans more than one page. Upgrade once by hand; later versions update normally:
npm install --global @xenoviz/ruk@latestUse bun install --global @xenoviz/ruk@latest for a Bun install, or download the executable for your platform from GitHub Releases for a standalone install.
The dashboard does not open
ruk ui prints the address to open. With --open, a missing browser opener is only a warning; copy the printed address instead. If the port you passed with --port is in use, choose another or omit --port to pick a free one.
If the page shows Offline, the ruk ui process has stopped; start it again. If it says the session ended, the page belongs to an earlier run. Each run prints a new one-time address, so open that one.
A tracked process survives release
Without --force, Ruk preserves the assignment when a recorded process does not stop gracefully. Inspect the process and retry. Forced release escalates to forceful process-tree termination.
On Windows, routine Ruk liveness checks use native process APIs and do not launch PowerShell. If a process remains, preserve the assignment and inspect the recorded process before considering forced recovery.
Shared mode fails checks
Return to managed mode. A successful dependency install does not prove that an isolated layout works with the repository's compiler, build tools, tests, and lifecycle scripts.
State is invalid
Ruk stores state under the Git common directory and fails visibly on corrupted or unsupported data. Do not silently replace state while assignments may be active. Preserve the diagnostic and inspect the repository before recovery.