Skip to main content
Start your dev server first (npm run dev or whatever your project uses), then open Rivet again. Rivet checks the ports common frameworks use; if yours runs somewhere unusual, point at it directly:
If port 4000 is taken, Rivet moves to the next free port on its own — or pin one with --rivet-port. Plain HTML projects don’t need a dev server at all: use --framework static (and --entry if your entry file isn’t index.html).
Rivet needs Node.js 22.13 or newer. Check with node --version, upgrade, then reinstall with the @latest tag so npm doesn’t hand you an old release:
Run rivet login in a terminal. It opens a browser sign-in and finishes on its own. If your agent reports an AUTH_REQUIRED error, this is the same fix. Check where you stand with rivet auth status.
In an existing project, Rivet uses git to keep each variant’s workspace separate, so the project needs to be a git repository (git init). To run without any git features, start Rivet with --no-git.
Re-run the install for that client (with --mcp where it applies) and fully restart it:
  • Cursor — quit and reopen, then check Settings → MCP for a green rivet entry.
  • Claude Desktop — confirm a rivet entry exists in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/), then restart the app.
  • Codex CLI — run cat ~/.codex/config.toml and confirm an [mcp_servers.rivet] section exists.
Setting up workspaces can take a few minutes. While rivet status reports variants.starting: true, the run is still getting ready — don’t cancel or retry, just wait (or watch live with rivet status --watch). If rivet wait <workId> exits with code 5, the work is still running; that’s a timeout, not a failure.
  • rivet --debug turns on verbose logging.
  • rivet status --watch streams live session state in the terminal.
  • Every command prints a JSON result with a stable error code — see exit codes.
  • Desktop app logs live at ~/Library/Logs/Rivet/ on macOS.

​
Still stuck?

Message the founder directly at [email protected] — replies are fast.