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.

• 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.

Terminals need the worker to be online and the worktree to have finished provisioning.

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 starts the script marked as the default.
• The other scripts are one menu away: right-click on web, or use the menu arrow on Mac and iOS.

Each script runs in its own terminal tab, which shows its state and a Run or Stop control. 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.

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

Browser tabs

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

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 worker 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 worker 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.