XOROX
Get started
XOROX
Sign inGet started

Reference

Troubleshooting

Fixes for the most common XOROX setup problems in Cursor.

Ruleset context doesn't seem to reach the agent

The hook fails open — if anything is wrong, your prompt still goes through, just without XOROX context, and nothing visibly errors. Check, in order:

  • .env in the project root has both XOROX_PROJECT_ID and XOROX_TOKEN set, and the credential hasn't been revoked.
  • .cursor/hooks.json has a beforeSubmitPrompt entry pointing at @xorox-ai/agent/hooks/before-submit.js. Re-run npm install @xorox-ai/agent if it's missing.
  • You've reopened the project in Cursor since installing or changing .env.
  • At least one Ruleset in the project is active, not inactive or archived.

Cursor was already open during installation

Cursor reads .cursor/hooks.json and .cursor/mcp.json when a project loads, not continuously. Reopen the project after installing, updating, or editing either file by hand.

The xorox MCP server shows up but its tools aren't available

Cursor detects a declared MCP server automatically but doesn't enable it. Open Cursor Settings → Tools & MCP, find xorox, enable it, then start a new Agent chat — a chat already open may still be using its old tool list.

The agent's first XOROX tool call asks for permission

That's expected — it's Cursor's own approval dialog, not an error. Choose Run to approve once, or Always run to stop it asking again for that tool.

"Missing XOROX_PROJECT_ID" or "Missing XOROX_TOKEN"

The agent couldn't find one of the required values. Confirm .env is in the root of the project Cursor has open (not a parent or child directory), and that both lines are present:

.env
XOROX_PROJECT_ID=your-project-id
XOROX_TOKEN=your-token

Credential invalid or revoked

A revoked credential can't be restored and a lost token can't be viewed again. Create a new credential from the project's Credentials tab and update .env — see Authentication.

The local runtime doesn't seem to start

Check that your OS and CPU architecture are supported — macOS (Apple Silicon or Intel), Linux (x64 or arm64), or Windows (x64 or ARM64). If they are, confirm the project's .xorox/runtime.json exists after sending at least one prompt — the runtime starts on first use, not at install time.

Port or connectivity issues

The runtime binds 127.0.0.1 only and picks the first free port between 47821 and 47921. A strict local firewall rule blocking loopback traffic in that range can prevent it from starting — this is rare, but worth checking if nothing else explains the failure.

After updating the package

Reopen the Cursor project once after running npm install @xorox-ai/agent@latest, so any migrated hook or MCP entries take effect and the background runtime restarts on the new version.

Start a new Agent chat after config changes

An Agent chat that was already open when you enabled the MCP server, changed .env, or updated the package may keep using stale results. When in doubt, start a new chat.