RELEASE · v0.2.23
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
Terminal QR invitations
Use rdzv host -q or --qr to also display the invitation as a terminal QR code. The QR contains the complete invitation text. Scan it and pass the resulting text to rdzv join. Widen the terminal or reduce its font size to keep the entire code visible.
Persistent background host
rdzv host --service --qr
This starts one background host under your current user, with a reusable invitation that remains unchanged across connections and service restarts. Only one guest can connect at a time. The host republishes after a session ends and retries failed Tor connections. Add --cutout to preserve an active session across recoverable transport failures. --session-timeout still limits each connection; --invite-timeout does not expire the service invitation.
The process is detached from the terminal. It does not install a system service or register login/reboot autostart. After a reboot or user-session termination, run rdzv service start to resume with the same invitation.
rdzv service status rdzv service invitation --qr rdzv service stop rdzv service start rdzv service rotate --qr rdzv service logs
Stopping closes the active connection and listener but retains the invitation. Rotation stops the host, replaces its credentials and onion identity, and starts it with a new invitation; the old QR no longer grants access. service rotate --cutout or --no-cutout changes transport mode while rotating.
For background approval mode, use host --service --approve. service status shows a pending request ID and command; decide with service approve --request ID or service deny --request ID. service approval on|off changes command approval. Computer access still requires separate per-session consent through these request controls; service revoke-computer revokes it. Service logs are private and rotate at 2 MiB with two retained backups.
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.
- Linux: x86_64, aarch64 (ARM64), or armv7l (32-bit ARM hard-float) with glibc 2.34 or newer: for example, Ubuntu 22.04+, Debian 12+, or Amazon Linux 2023, where the distribution supports that architecture.
- macOS: version 11 or newer on Apple Silicon.
- Windows: Windows 10 version 1809 or newer, including Windows 11, on x64. A writable local application-data directory on NTFS and a 64-bit PowerShell terminal are required for installation. Built-in Windows PowerShell 5.1 and PowerShell 7 are supported.
- Linux and macOS bootstrap utilities:
curl,tar,sha256sumorshasum, standard shell utilities, andgetconfon Linux. - A writable user directory on a filesystem that permits execution.
- Intel Macs, native Windows ARM64, older glibc, and musl-based hosts such as Alpine are not packaged in this release. Unsupported platforms stop before installation instead of asking for elevation.
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
- Waiting for the onion service: invitations are issued after descriptor-upload acknowledgments. If a descriptor lookup stalls, the joiner requests another Tor-selected directory after ten seconds. Transport and handshake failures before credentials are sent are retried using separately isolated Tor circuits. A stalled private Tor instance is replaced automatically before authentication; the host can also restart publication before issuing an invitation. Join startup, descriptor lookup, and connection attempts share a three-minute deadline, bounded by the invitation's remaining lifetime.
- Connection lost during authentication: the invitation may have been consumed. Start a fresh host session rather than assuming it is reusable.
- Permission denied after connecting once: start a new host session; the previous invitation is consumed.
- Execution denied under home: local policy or a no-execute filesystem can prevent running the bundle. The installer does not bypass that policy.
- Unsupported platform: no system packages are changed and no privilege prompt is attempted.