distant: driving a remote machine's files and processes from one CLI

One command surface over Docker, host and SSH backends

distant is a library and a set of tooling for remote filesystem and process operations, and the Cargo workspace shows how the pieces are arranged. There are five member crates: distant-core, distant-docker, distant-host, distant-ssh and distant-test-harness, and the top-level package is the command line interface whose description is to operate on a remote computer through file and process manipulation, categorised as a command-line utility. The backends are gated behind cargo features, with the default set being docker, host, ssh and pty. The host feature additionally pulls in macos-fsevent, and the ssh feature is tied to a serde feature, which tells you the SSH backend has a serialisable configuration path while the others do not. The workspace declares itself as version 0.21.0-dev and the individual crates are pinned to that exact version with a path dependency, so the whole workspace moves together.

The alpha warning is on the first screen of the README

The README opens with a construction sign emoji and a parenthetical note that this is alpha stage software in rapid development which may break or change frequently. The repository description repeats it, calling it a library and tooling that supports remote filesystem and process operations and marking it with the same construction signs. This is worth taking at face value rather than reading past, because it changes how you should treat the release numbers. The release list is a nightly build from 2026-04-18, a latest build from 2023-07-06 and v0.20.0 from 2023-07-15. So the tagged release on crates.io is nearly three years old, while the nightly build is from earlier this year, and the workspace source is on 0.21.0-dev. The last push to the repository was on 2026-04-18, the same day as the nightly build, and the repository is not archived. In other words, the source is moving and the published crate is not, and the version you get depends on where you get it from.

Installing with a shell script on Unix and PowerShell on Windows

The installation instructions differ by platform, and the Unix one carries a detail worth copying exactly.

# Need to include -L to follow redirects as this returns 301
curl -L https://sh.distant.dev | sh

# Can also use wget to the same result
wget -q -O- https://sh.distant.dev | sh

The comment explains the -L flag: without it the request returns a 301 and the script never runs. The wget form is offered as an equivalent. On Windows the instructions are a PowerShell pair, where the first line sets the execution policy to RemoteSigned for the current user, described as optional and needed to run a remote script the first time, and the second pipes the same script through irm and iex. Both platforms link to their own page on the documentation site for details. The Rust requirement is stated in the badge and in the manifest, 1.88.0 or newer, and the crate is published on crates.io with docs on docs.rs.

Three commands that show the shape of the tool

The usage section is three commands, and they cover the three things the tool does.

# SSH into a server and open a shell
distant ssh example.com

# Read the remote current working directory
distant fs read .

# Run a command on the remote machine
distant spawn -- ls -la

The first is an interactive shell over SSH. The second is a filesystem operation, and the naming has a remote prefix, fs, followed by a verb, read, and a path. The third runs a process, and the double dash separates the tool's own options from the command being run, so ls -la is not parsed by distant. That separation is the detail that makes the tool composable with ordinary command line expectations, and it is the reason you can wrap a distant spawn call in a script without quoting gymnastics. The documentation site has a getting started page on usage, and the repository also carries pages on building from source, testing, the plugin specification, publishing releases and the changelog.

A plugin specification, and a test harness crate

The repository has a docs directory with a plugin specification, which is the extension mechanism, and a distant-test-harness crate, which is the testing mechanism. Having the test harness as a workspace member rather than a dev-dependency of one crate is the detail that matters, because it means the harness is versioned and shared across the backends rather than duplicated per target. A tool that talks to Docker, to a host process and to an SSH server has three quite different failure modes, and a shared harness is how you avoid testing only the one that is easy. The workspace also has a rustfmt.toml, a flake.nix and flake.lock for a Nix development environment, a patches directory, a build.rs at the root, a scripts directory, and a .cargo directory. The CI workflow is referenced through the badge, and the lints configuration in the manifest is strict, with warnings denied and clippy's all set to deny, so the code is held to a high bar even while the project calls itself alpha.

Dual licensing, small release surface, and a deliberately small binary

The licence is the Apache License version 2.0 or the MIT licence at your option, with both LICENSE-APACHE and LICENSE-MIT present at the root, and the workspace package metadata records the same choice. The build profile in the manifest is tuned for size rather than speed, with opt-level set to z, LTO enabled, a single codegen unit, symbols stripped, and panic set to abort. For a CLI that gets downloaded and run on machines you do not control, that is a sensible set of choices, and panic abort rather than unwinding also means a crash ends the process instead of leaving a half-torn-down remote operation. The dependency list shows the shape of the interface layer, with clap for argument parsing and clap_complete for shell completions, crossterm and console for terminal handling, dialoguer for prompts, anyhow and thiserror for error handling, derive_more for enum helpers, and the distant-* crates for the backends themselves.

Editorial conclusion

distant fits a developer or team that needs the same script to work against a local Docker container, a remote host and an SSH box, and who values a typed Rust client over a pile of shell scripts. It does not fit a production pipeline that needs a stable interface, since the project labels itself alpha and says it may break or change frequently. Verify first that the backend for your target is the one you need, read the plugin specification before you write your own, and treat the version in the workspace manifest as the honest one, because the published crate on crates.io is older than the source.

Frequently asked questions

Official sources

1. chipsenkbeil/distant on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases