Rivets
Documentation

Terminals and scripts

Every task’s worktree is a real checkout on a worker, and you can work in it directly. Open a terminal or run the repository’s scripts from any client.

Terminals

Choose + in the task’s tab strip and pick Terminal. The shell opens in the task’s worktree on the worker, as the worker’s OS user.

The same menu has Claude Code and Codex, which start the agent interactively in a terminal tab. They appear when the worker has that agent installed and signed in. The menu also starts a new Chat or Review changes.

  • Private to you. A shell terminal is visible only to the person who opened it.
  • Up to 16 per person. Each member can have 16 terminals open at once. Script terminals do not count toward this.
  • Survives reconnects. Scrollback is kept on the worker, encrypted with a key held in the OS credential store. If your connection drops or you switch devices, reopening the terminal restores it. If no secure key store is available, scrollback is not saved at all.
  • Closed when abandoned. A shell that nobody is viewing and that prints nothing for 30 minutes is closed.

Terminals need the worker to be online, the worktree to have finished provisioning, and the task to be approved if it is waiting for approval. You also need access to the task’s worker: on a worker its owner has not shared with you, terminals are unavailable.

Run scripts

A repository can define named scripts in its checked-in .rivets/settings.toml, such as a dev server or a test run. They appear behind the Run control in each client’s terminal strip:

  • A single press of Run starts the script marked as the default. While a script is running, the same button shows Stop.
  • The other scripts, including the repository’s setup script, are in the menu next to it.

Each script runs in its own terminal tab, which shows its state. Right-click a script tab (long-press on iPhone and iPad) for Run again or Stop. Closing a script tab only hides it for you: the script keeps running until you stop it. Script terminals are read-only: you can scroll and select output, but not type into them. Unlike shells, anyone with access to the task can read them, so a failed setup is visible to whoever reviews the task.

Stopping a script sends SIGTERM, then SIGKILL after 5 seconds if it is still running.

A run script that serves a web page can declare a preview. While it runs and listens, Open preview appears beside Run and shows the server in the task’s Preview tab. Each task has its own ports, starting at $RIVETS_PORT, so two tasks can run the same dev server side by side. See Previews.

See The .rivets directory for how to define scripts, and how a worker operator can turn them off.

Browser tabs

The + menu also has Browser. On Mac, iPhone, and iPad it opens a native browser tab inside the task. On web, Browser (new browser tab) opens a new tab in your browser.

The same menu has Preview, which shows the task’s own dev server. See Previews.

Faster paths

By default, terminal traffic goes through the Rivets relay. Two paths can make it faster.

Same machine

When your client runs on the same machine as the task’s worker, terminal traffic stays on 127.0.0.1 instead of going through the relay. The same-machine path also serves files and diffs straight from the worker, which makes browsing a local task instant. Rivets still orders and records everything, and falls back to the relay on any error.

This is on by default. Turn it off with:

rivets connect --no-loopback

Direct transport over Tailscale

If the worker and your devices share a Tailscale network, you can send terminal traffic over it directly:

rivets connect --direct
  • Opt-in and terminal-only. File reads stay on the relay.
  • Uses your existing Tailscale setup. Rivets never installs Tailscale, signs a machine in, or changes your tailnet ACLs. It configures a single Tailscale Serve path pointing at a local gateway, and removes only what it added.
  • Still authorized by Rivets. Every direct connection presents a one-use ticket that expires after 60 seconds and is checked against your current access.
  • Always falls back. If the direct path times out, is rejected, or disconnects, the terminal continues over the relay without losing input.

Turn it off with --no-direct.

Type to search the docs.