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:

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)

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.

5.3 KiB Raw Blame History