🚧 (Alpha stage software) Library and tooling that supports remote filesystem and process operations. 🚧
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Chip Senkbeil a023b8f22d
Add reconnect feature to table list
4 days ago
.cargo Update to attempt more linux release builds 2 weeks ago
.config Rewrite to support custom authentication, handshakes for encryption/compression, and reconnecting (#146) 2 weeks ago
.github/workflows Add heartbeat support (#153) 4 days ago
distant-core Add heartbeat support (#153) 4 days ago
distant-net Add heartbeat support (#153) 4 days ago
distant-ssh2 Add heartbeat support (#153) 4 days ago
src Add heartbeat support (#153) 4 days ago
tests Add heartbeat support (#153) 4 days ago
.dockerignore Add dockerignore to speed up dockerfile 6 months ago
.gitignore Add native ssh (#57) 1 year ago
BUILDING.md Refactor to use distant manager (#112) 4 months ago
CHANGELOG.md Add heartbeat support (#153) 4 days ago
Cargo.lock Add heartbeat support (#153) 4 days ago
Cargo.toml Add heartbeat support (#153) 4 days ago
Dockerfile Minor documentation changes and update dockerfile to build from source 6 months ago
PUBLISH.md Update referenced versions in READMEs and add note about doing so to PUBLISH.md 3 months ago
README.md Add reconnect feature to table list 4 days ago
rustfmt.toml Refactor to use distant manager (#112) 4 months ago


distant - remotely edit files and run programs

Crates.io Docs.rs CI RustC 1.61+

🚧 (Alpha stage software) This program is in rapid development and may break or change frequently! 🚧


The distant binary supplies both a server and client component as well as a command to start a server and configure the local client to be able to talk to the server.

Additionally, the core of the distant client and server codebase can be pulled in to be used with your own Rust crates via the distant-core crate. The networking library, which is agnostic of distant protocols, can be used via the distant-net crate.


Prebuilt Binaries

If you would like a pre-built binary, check out the releases section.

Building from Source

If you have cargo installed, you can directly download and build the source via:

cargo install distant

Alternatively, you can clone this repository and build from source following the build guide.

Backend Feature Matrix

Distant supports multiple backends to facilitate remote communication with another server. Today, these backends include:

  • distant - a standalone server acting as the reference implementation
  • ssh - a wrapper around an ssh client that translates the distant protocol into ssh server requests

Not every backend supports every feature of distant. Below is a table outlining the available features and which backend supports each feature:

Feature distant ssh
Filesystem I/O
Filesystem Watching
Process Execution
System Information
  • means full support
  • ⚠ means partial support
  • means no support

Feature Details

  • Capabilities - able to report back what it is capable of performing
  • Filesystem I/O - able to read from and write to the filesystem
  • Filesystem Watching - able to receive notifications when changes to the filesystem occur
  • Process Execution - able to execute processes
  • Reconnect - able to reconnect after network outages
  • Search - able to search the filesystem
  • System Information - able to retrieve information about the system


Starting the manager

In order to facilitate communication between a client and server, you first need to start the manager. This can be done in one of two ways:

  1. Leverage the service functionality to spawn the manager using one of the following supported service management platforms:
  1. Run the manager manually by using the listen subcommand

Service management

# If you want to install the manager as a service, you can use the service
# interface available directly from the CLI
# By default, this will install a system-level service, which means that you
# will need elevated permissions to both install AND communicate with the
# manager
distant manager service install

# If you want to maintain a user-level manager service, you can include the
# --user flag. Note that this is only supported on MacOS (via launchd) and
# Linux (via systemd)
distant manager service install --user

# ........

# Once you have installed the service, you will normally need to start it
# manually or restart your machine to trigger startup on boot
distant manager service start # --user if you are working with user-level

Manual start

# If you choose to run the manager without a service management platform, you
# can either run the manager in the foreground or provide --daemon to spawn and
# detach the manager

# Run in the foreground
distant manager listen

# Detach the manager where it will not terminate even if the parent exits
distant manager listen --daemon

Interacting with a remote machine

Once you have a manager listening for client requests, you can begin interacting with the manager, spawn and/or connect to servers, and interact with remote machines.

# Connect to my.example.com on port 22 via SSH and start a distant server
distant client launch ssh://my.example.com

# After the connection is established, you can perform different operations
# on the remote machine via `distant client action {command} [args]`
distant client action copy path/to/file new/path/to/file
distant client action spawn -- echo 'Hello, this is from the other side'

# Opening a shell to the remote machine is trivial
distant client shell

# If you have more than one connection open, you can switch between active
# connections by using the `select` subcommand
distant client select '<ID>'

# For programmatic use, a REPL following the JSON API is available
distant client repl --format json


This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or apache-license) MIT license (LICENSE-MIT or mit-license) at your option.