rmote

rmote runs Python functions through SSH, docker exec, kubectl exec, a local Python process, or another bidirectional stream connected to Python. See Transports for the common model, including prepared nc relays. Built-in tools manage files, commands, packages, services, and users. You can also define your own tools and return Python values from them.

Install rmote locally with Python 3.11 or newer:

python -m pip install rmote

The target needs Python 3.11 or newer but no rmote installation. rmote sends tool code over the connection when it is first used. Package and service tools require their system commands and sufficient permissions on the target.

To operate without an agent, rmote runs standard python3 -qui on the target:

• -q (quiet): suppresses Python’s startup banner and copyright notices.

• -u (unbuffered): forces unbuffered stdout/stderr streams for instant packet delivery.

• -i (interactive): reads and executes statements from stdin even without a TTY.

A free-threaded interpreter works on both sides. rmote has no compiled extension, and it guards the state it shares between threads with its own locks. The tests cover 3.13t and 3.14t on Linux and macOS.

Start with a Deployment

Follow the Quickstart to deploy a Redis cache in a disposable Docker container. You will install a package, render a systemd unit, start the service, and check that it works. The deployment code also works over SSH by replacing the connector.

Choose a Guide

Task	Guide
Connect through SSH, containers, local Python or another byte stream	Transports
Write a remote operation and return Python data	Writing Tools
Explore a host from a Python console	Python REPL
Collect and cache host state	Facts
Apply an operation to several hosts	Work with Multiple Hosts
Synchronize file contents in either direction	FileSync
Synchronize files or trees from the command line	File and directory synchronization
Render a configuration file	Templating
Write and transfer a custom template filter	Writing template filters
Find a built-in operation	Built-in Tools
Configure synchronous connections and deadlines	Synchronous Connection
Use connections from an async application	Protocol and Tool Support
Understand code transfer, state, and cancellation	Concepts

Use rmote.sync.Connection for synchronous scripts and rmote.protocol.Protocol for async applications. Both clients call the same tools. Use rmote only with trusted hosts and tool code: the target executes transferred Python, and the client unpickles returned data.

User Guide

• Quickstart
  • Install rmote
  • Prepare a Disposable Host
  • Connect and Run a Command
  • Create an Administrator
  • Grant and Check sudo Access
  • Install Redis
  • Render a systemd Service
  • Write the Unit and Start the Service
  • Check an Unchanged Rerun
  • Write a Tool for Your Application
  • Use the Same Deployment over SSH
  • Clean Up and Continue
• Transports
  • Commands that start Python
  • Selecting a transport in the CLI
  • Relays and already prepared streams
• TLS over a transport
  • Why use TLS?
  • CLI options
  • Controller certificate
  • Trust boundary
  • Local test credentials
• Writing Tools
  • Define One Operation
  • Modules and packages as tools
  • Keep Tool and Client Code Separate
  • Return Structured Data
  • Handle Remote Errors
  • Choose a Method for the Work
  • Run a Command and Return Its Output
  • Stream a Long Result
  • State and Repeated Calls
  • Define an Inline Tool
• Python REPL
  • Connect
  • Inspect the host
  • Define a tool
  • Scripts and exit
• File and directory synchronization
  • Directory and file behavior
  • Exclusions and deletion
  • Logs and options
• Interactive shell
  • The transport is a command
  • Terminal or pipes
  • Choosing what runs
  • Closing the session
  • Window size and TERM
  • Troubleshooting
  • Sessions from Python
  • Limits
• SSH clients over rmote
  • Message of the day
  • Automatic startup from SSH config
  • One rule for a family of hosts
  • Transport and destination
  • TLS for the rmote transport
  • Terminal behavior
  • Stopping the server
  • Supported OpenSSH requests
  • Agent forwarding
  • SFTP without a remote SFTP server
  • Other requests
• Work with Multiple Hosts
  • Collect Results with a Concurrency Limit
  • Keep Results When One Host Fails
  • Reuse Connections for Related Operations
  • Use a Synchronous Client
• Templating
  • Why rmote has its own template engine
  • Using the engine
  • Context and missing values
  • Expressions
  • Filters
  • Conditions and Loops
  • Assignments
  • Whitespace and Comments
  • Compilation and intermediate representation
  • The render_template Helper
  • The RenderTemplate Tool
  • Diagnose template errors
  • Measuring performance
• Writing template filters
  • Define a filter in a Python file
  • Register and call the filter
  • Instance state and input data
  • Return collections and objects
  • Validate values and handle missing input
  • Make the class portable
  • Render remotely with your filters
• Concepts
  • Client Interfaces and Resource Ownership
  • Cancellation and Logging
  • Bootstrap Flow
  • Wire Protocol
  • Minimal bootstrap and lazy dependencies
  • Tool Serialization Lifecycle
  • Standard Streams and Trust
  • Concurrency Model

Releases

• Release notes

API Reference

• API Reference
  • Synchronous Connection
  • Protocol and Tool Support
  • Subprocess helpers
  • Platform requirements
  • Immutable snapshots
  • Tool result cache
  • Dataclass serialization
  • Shell Client
  • Template compiler and interpreter
  • Template filters
  • Built-in Tools