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.16 or newer on 22.x, or Node.js 24 or newer. Node.js 23 isn’t supported. Check with node --version, upgrade, then reinstall with the @latest tag so npm doesn’t hand you an old release:
Ask your agent to open Rivet again. Rivet opens a sign-in page in your browser, or your agent shares the link with you. Finish signing in there, then open Rivet once more. You can also run rivet login in a terminal. 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 by name, then fully restart it. If you installed with --no-mcp, run it again without that flag.
  • 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 shows your dev server’s startup output in the preview. If a dependency install failed, you see the installer’s error instead. Fix what it points to — often a missing package or a config error — then retry: click Retry preview, or for a past direction, select it again.If the error says the port is already in use, another process is holding it. Stop that process, then retry.
  • 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.