Rivets
Documentation

Quickstart

This guide takes you from a new account to a merged pull request. You need a machine that can run a worker, with Claude Code or Codex installed and signed in, and a GitHub repository you can install an app on.

Sign-up is one guided flow, the same on the web and in the Mac app. If you stop partway, you pick up at the same step on any device.

1. Create your account and organization

How you start depends on whether you are creating an organization or joining one.

Create an organization

  1. Open app.rivets.dev, or the Mac app, enter your email and choose Continue.
  2. On Create your account, choose a password of at least 8 characters and choose Create account.
  3. On Get Rivets for your team, set the number of seats and choose Continue to checkout, then finish checkout in your browser. If someone else got the license, choose I have a license key instead and paste the lic_ key from their email. See Licenses and seats.
  4. On Set up your profile, check your name and photo, then choose Continue.
  5. On Create your organization, enter a name and choose Create organization.

Rivets suggests your name, photo, organization name and logo from your email address. You can change any of them.

Join an organization

Open the invite link you received. It opens sign-up with your email filled in. Create an account, or sign in, then choose Join followed by the organization’s name. You can also paste the link under I was invited to a team on Get Rivets for your team. If you finished sign-up earlier, the link opens an invitation page instead: choose Accept invite.

Members skip the license, organization, GitHub and Linear steps. After Set up your profile, continue with step 2 below. Once an owner has given you access to a repository, go on to step 4.

2. Choose where agents run

A worker is the machine where agents run. On Where should agents run?, pick one or both options and choose Continue.

This Mac

In the Mac app, This Mac is selected for you. The app sets itself up as a worker for your organization. It runs whenever Rivets is open on this Mac, with nothing to install. The worker is yours alone until you share it. Adjust it later under Settings › This Mac.

On the web, choose Download for Mac to get the Mac app, then sign in there.

A remote machine

Choose A remote machine for a server, a cloud VM or another computer. Rivets shows a one-line command. Run it in a terminal on that machine:

curl -fsSL https://app.rivets.dev/install.sh \
  | RIVETS_TOKEN=<token> sh

It installs the rivets CLI, connects it to your organization, and keeps the worker running in the background. The command contains a one-time token. It expires 15 minutes after Rivets creates it, so run the command soon after copying it. Rivets shows the machine as connected when it comes online.

On Windows, choose On Windows? Show the PowerShell command, and run it in PowerShell on the PC:

$env:RIVETS_TOKEN='<token>'
irm https://app.rivets.dev/install.ps1 | iex

You can add more workers later from Settings › Workers with Add worker. Run rivets doctor on a machine to check its prerequisites. See Connect a worker.

3. Connect GitHub and add a repository

Organization owners connect GitHub and repositories.

  1. On Connect GitHub, choose Connect GitHub and install the Rivets GitHub App on your GitHub account or organization. Grant it the repositories you want Rivets to work on.
  2. Optionally, connect Linear on Connect Linear, or choose Skip for now. See Linear.
  3. On Rivets, everywhere, choose Open Rivets.
  4. Choose Connect repository, pick a repository, and choose Add repository.

If you skipped GitHub during sign-up, Connect repository offers Connect GitHub first. See GitHub for the permissions the app requests and why.

4. Create a task

  1. Choose New task, or press ⌘N.
  2. Pick the repository.
  3. Describe what you want the agent to do. Attach files if they help.
  4. Optionally, use Start from to begin from a pull request, a branch, or a Linear issue instead of the default branch.
  5. Choose the agent and model, the reasoning effort, and the worker cluster. Auto picks the best available worker.
  6. Choose Create.

Rivets names the task and its branch, provisions a worktree on the worker, and starts the agent. See Creating tasks.

5. Watch and steer

The transcript streams as the agent works. The Changes tab in the inspector follows each edit live. To redirect the agent, type in the composer and send. By default, the message reaches the agent while it works: Claude Code reads it at its next step without stopping, and Codex stops its current turn to read it. Teammates with access can watch and steer the same task. See Steering and multiplayer.

6. Open a pull request and merge

  1. Open the Checks tab in the inspector.
  2. Choose Create PR. Rivets writes any missing title, description, and commit message, then commits, pushes, and opens the pull request.
  3. Follow the check runs and reviews in Checks. Use Fix on an unresolved review thread to send it to the agent.
  4. When checks pass, choose Merge.

By default, Rivets archives the task once its pull request is merged. See Pull requests and merging.

Next steps

  • Turn on two-factor authentication under Settings › Security in the web app: Security.
  • Add a checked-in setup script so every worktree starts warm: The .rivets directory.
  • Invite teammates from Settings › Organization in the web app, or Settings › Members in the Mac app, and give them access to the right repositories: Teams and permissions.
  • Connect Linear if you skipped it.

Type to search the docs.