distant - remotely edit files and run programs

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

Details

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.

• Asynchronous in nature, powered by tokio
• Data is serialized to send across the wire via msgpack
• Encryption & authentication are handled via XChaCha20Poly1305 for an authenticated encryption scheme via RustCrypto/ChaCha20Poly1305

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.

Installation

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.

Example

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:

• sc.exe for use with Window Service (Windows)
• Launchd (MacOS)
• systemd (Linux)
• OpenRC (Linux)
• rc.d (FreeBSD)

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

License

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.