RELEASE · v0.2.22

Quickstart

Run the host on the machine you want to share. Run the client on the machine you or your agent will connect from. Choose the command for each machine's operating system; the host and client do not need to use the same one. Use the same commands for your first session and every session after it.

1. Start the host

Open a terminal on the machine you want to share and run:

Linux / macOS

curl -fsSL https://host.rdzv.sh | sh

Windows

Run in a 64-bit PowerShell terminal:

& ([scriptblock]::Create((irm https://host.rdzv.sh/host.ps1)))

The bootstrap selects the current release, downloads and verifies it when needed, and starts a host session. A matching local copy is reused automatically.

Share the highlighted rv1.… invitation privately with your guest. Keep the host running. It displays Connected. when the guest authenticates. This is a new shell under your account, not a sandbox.

2. Join

On the connecting machine, run the command for its operating system:

Linux / macOS

curl -fsSL https://join.rdzv.sh | sh

Windows

& ([scriptblock]::Create((irm https://join.rdzv.sh/join.ps1)))

Paste the invitation at the prompt. For an AI agent, use Join as an agent below instead. Write remote commands for the host's shell, regardless of the client's operating system.

3. End access

Exit the remote shell, press uppercase D or Ctrl-C on the host, or let the session deadline expire. No Enter is needed for host keyboard controls. Host-initiated shutdown closes SSH before the Tor transport. The first successful authentication consumes the invitation, closes the TCP listener, and removes the onion service's introduction path while preserving the established session. Disconnect never reactivates it. One interactive connection can run many commands; --command runs one command and ends that session.

Defaults are ten minutes to redeem and twelve hours of access. Both host and join support --session-timeout SECONDS; the earlier limit ends the connection. A new host invocation creates new service identities and credentials. After installation, set custom limits with:

rdzv host --invite-timeout 300 --session-timeout 1800

Join as an agent

Run this where your agent executes commands:

Linux / macOS

curl -fsSL https://join.rdzv.sh | sh -s -- -a --invitation "<invitation>"

Windows

& ([scriptblock]::Create((irm https://join.rdzv.sh/join.ps1))) -RendezvousArguments @('-a', '--invitation', '<invitation>')

Agent mode keeps one SSH connection in the background and prints exact local commands. session exec SESSION 'command' runs a command, streams its stdout and stderr, and returns its exit code in one call. Each execution uses a fresh shell without a PTY. Set the working directory within the command using the host's shell syntax. The controller exits when the session ends or reaches its lifetime limit, which includes startup and approval waiting.

The homepage's Human / Agent switch copies a ready-to-paste agent prompt. Append your invitation to it; the website does not receive the invitation.

Pass options and automate commands

After installation, the rdzv command and its options work across supported platforms. The remaining examples use this installed command. On Linux/macOS, the launcher is ~/.local/bin/rdzv; add ~/.local/bin to your PATH or use that full path. On Windows, the installer adds the runtime's bin directory to your user PATH. Local launchers do not check for updates; use the website commands to fetch the current release. To pass options through the bootstrap:

Linux / macOS

curl -fsSL https://host.rdzv.sh | sh -s -- --approve --verbose

Windows

& ([scriptblock]::Create((irm https://host.rdzv.sh/host.ps1))) -RendezvousArguments @('--approve', '--verbose')

You can supply an invitation directly:

rdzv join --invitation 'rv1.…'

Direct invitations are visible in shell history and process arguments. To avoid placing the invitation there, supply a file accessible only to your account. For automation, add --command, using a local invitation-file path and a command appropriate for the host:

rdzv join --invitation-file "<local-invitation-file>" --command "<remote-command>"

--invitation and --invitation-file are mutually exclusive. Interactive shells use your terminal; automated commands through the bootstrap receive no standard input. Hosts use their configured shell on Linux/macOS and Windows PowerShell on Windows. Windows interactive sessions use ConPTY; approved and agent commands use fresh PowerShell processes with separate output streams. Invitations and the SSH protocol work across platforms.

Approval mode for people and agents

rdzv host --approve

Start with approval enabled using --approve (also --approval), or press a on the host while no decision is pending to toggle it on or off. Approval requires a host terminal and works with both human and agent guests.

A human guest normally uses an interactive terminal. When approval is enabled, the joiner switches to an approval> command-entry prompt. Each submitted command uses the same non-PTY execution and host approval as agent commands. Commands run in fresh shells; set the working directory within each command using the host's shell syntax. Turning approval off returns the guest to the retained interactive shell, including its directory and variables. Approved commands do not change that shell's state. Switching uses channels within the existing SSH connection, never another invitation or Tor connection. Start updated host and join sessions to use this protocol.

The host logs the complete command before asking Approve command?. Press a to approve it, d to deny it, or A to approve it and turn approval off. Denied commands do not execute and return status 126. Repeated unbound keys expand the prompt to Approve command (a/A/d)?. A human returns to the interactive terminal after the current approved command finishes if approval was turned off. Ctrl-C at the guest's command prompt clears its input; during execution or an approval wait it cancels that command. Ctrl-D on an empty command prompt closes the session.

While approval is enabled, the host rejects interactive input, and the joiner pauses display of the retained terminal's output. Switching modes discards unfinished local command-entry text. Already-accepted input and running commands are not retroactively subject to approval; turning approval on does not stop them. Agent commands continue through their existing session controls and follow the host's current approval setting.

The idle bottom bar shows a: approval mode, D: disconnect when approval is off and A: approve all, D: disconnect when it is on. During a decision it shows a: approve, A: approve all, d: deny, D: disconnect.

Computer use for agents

Agent sessions can request screen capture and mouse/keyboard control over their existing SSH connection. Start the host in a terminal on the desktop to control. The agent's initial instructions include:

rdzv session computer enable SESSION

The host must explicitly allow this separate, session-scoped request with a or deny it with d, even when command approval is off. After approval and OS permission checks, the agent receives exact commands for screenshots, pointer movement, click/double-click, drag, scrolling, text entry, and key combinations. The host logs each request and its outcome, including submitted text. Press x locally to revoke computer use while keeping the shell connection open; D disconnects everything.

An input command's successful reply means its events were posted, not that the application accepted the intended text or completed the task. Capture another screenshot to verify the result, especially before submitting a form or pressing Enter after typing.

rdzv session computer screenshot SESSION --output rdzv-screen-1.png
rdzv session computer click SESSION --frame FRAME_ID --x 640 --y 420
rdzv session computer scroll SESSION --frame FRAME_ID --x 640 --y 420 --dy 5
rdzv session computer type SESSION --text "Hello"
rdzv session computer key SESSION --keys "ENTER"
rdzv session computer disable SESSION

Commands return JSON. A screenshot is a PNG saved on the joiner's machine at a new, private output path; existing files are never overwritten. Load it with your agent's image tool. Pointer coordinates are pixels in that screenshot, with the origin at the top left. The returned frame ID maps those pixels to the host's display, including Retina scaling. A frame expires after 120 seconds or the next capture; changed display geometry requires another capture. Positive scroll steps move down/right. Capture again after actions to inspect the result. Screenshots are bounded to 32 MiB and 32 megapixels.

Screenshots are downsampled on the host to at most 1,600 pixels on the longest edge before transfer. Retina captures are also limited to the display's logical size; use coordinates from the returned image. Interrupted transfers retry up to three attempts on the existing connection without repeating mouse or keyboard input. Channel timeouts leave the shell available. A lost SSH connection still ends the session and requires a new invitation.

macOS: the host needs Accessibility and Screen Recording permissions (called Screen & System Audio Recording on some versions). Allow the application macOS identifies, which may be the launching terminal, under System Settings > Privacy & Security. Retry enable after granting access, restarting the host if macOS requires it. Updates may require renewed approval; the CLI does not install a separately signed desktop helper. Use CMD for Command shortcuts. A joiner does not need these desktop permissions.

Linux: computer use currently requires an X11 desktop with XTEST and the desktop's libX11/libXtst libraries. Capture covers the whole X11 desktop. Text entry uses the active keyboard layout and rejects unavailable characters before typing. Wayland/XWayland computer use is not supported in this release; shell hosting and joining remain available. Mac hosts can enumerate displays and select one with --display.

Windows: start the host in a terminal on the signed-in desktop. Screen capture, display selection, pointer input, scrolling, Unicode text, and keyboard shortcuts use native Windows APIs. Screenshots account for per-monitor display scaling. Use WIN for Windows-key shortcuts and a local Windows output path such as .\rdzv-screen-1.png on Windows joiners. Computer use has the same separate consent and x revocation controls on every platform.

Watch the session

The host logs SSH exec commands, interactive input, and output with labeled streams. Typed human input stays on the same log line until Enter. Terminal logs are bounded. Use --verbose to capture a full private transcript and show a bounded terminal mirror; press v to enable capture or m to return to minimal logging:

rdzv host --verbose

Interactive human logs record keystrokes, including editing controls, rather than reconstructing executed commands. The human PTY combines STDOUT and STDERR; agent exec requests keep the streams separate. Guest command output is unchanged. See the CLI reference for every host, join, and agent-session option, generated from the current release's --help.

Connection diagnostics

Both host and join accept -v / --verbose. Diagnostics go to standard error and show Tor bootstrap progress and elapsed time. The host also shows descriptor upload attempts, failures, the number accepted out of eight distinct directories, incoming SSH connections, authentication outcomes, and onion service removal. The joiner shows descriptor-directory lookups, numbered connection attempts, retry failures, time remaining, and onion-stream/SSH handshake timing. Agent mode forwards these startup diagnostics too.

rdzv host -v
rdzv join -v
rdzv join -a -v --invitation "<invitation>"

Descriptor acknowledgments confirm publication; they do not guarantee that the guest's circuits are ready. Creating and removing the service dynamically does not change Tor's routing or guarantee faster connections.

Supported environment

Supported platforms can host or join human and agent sessions. Python, Tor, and SSH dependencies are bundled. No administrator account, root, sudo, Homebrew, developer tools, WSL, OpenSSH service, or system Python is required.

Inspect before installing

Download the installer for your operating system, inspect it, then run it to install without starting a session.

Linux / macOS

Read the installer or download it first:

curl -fsSLo install-rdzv.sh https://host.rdzv.sh/install
less install-rdzv.sh
sh install-rdzv.sh

Windows

Read the installer or download it first:

Invoke-WebRequest https://host.rdzv.sh/install.ps1 -UseBasicParsing -OutFile install-rdzv.ps1
Get-Content .\install-rdzv.ps1
& ([scriptblock]::Create((Get-Content -Raw .\install-rdzv.ps1)))

Read the application and packaging source and bundle manifest. The runtime archive is delivered in fixed-size parts, joined locally, and verified as a whole using SHA-256 before extraction. The installer's checksum is served by the same publisher; this is integrity checking, not an independent signature.

Startup and latency

Rendezvous reuses Tor's public directory cache to reduce repeated bootstrap downloads. Each session still creates fresh service keys, credentials, and Tor process state. Concurrent sessions use separate cache slots.

For a shorter host-side route, opt into Tor's experimental single-onion mode:

rdzv host --single-hop

This reduces the host-side introduction and rendezvous circuits from three hops to one and gives up host-location anonymity. Client routing, client authorization, SSH encryption, host-key pinning, and single-use access remain in place. Default routing is unchanged. Startup, service publication, and keystroke round-trip time depend on the Tor network; neither caching nor single-hop mode guarantees a particular delay.

Caching, updates, and removal

Every invocation of the website command fetches the current bootstrap. The installer verifies a replacement before selecting it, then removes verified older installations that are not in use. Runtime leases protect current sessions; process inspection protects sessions started by older releases. Busy installations are retained until a later installer invocation can remove them. Cleanup is deferred when usage cannot be checked. Local launchers do not check for updates when run directly. No shell configuration is required for the website commands. Removing old runtimes does not guarantee that macOS privacy permissions persist across updates.

Linux / macOS

Runtimes, session files, and public Tor directory caches are kept under ~/.local/share/rendezvous. To remove them, stop your sessions and remove that directory, ~/.local/bin/rdzv, and ~/.local/bin/rendezvous.

Windows

Runtimes, session files, and public Tor directory caches are kept under %LOCALAPPDATA%\Rendezvous. The installer includes a native rdzv.exe launcher and adds the current runtime's bin directory to your user PATH. To remove the installation, stop your sessions, remove %LOCALAPPDATA%\Rendezvous, and remove its runtime bin entries from your user PATH.

Troubleshooting

Read the security model →