serial-exec

serial-exec is an OOB utility for command execution over a serial console.

It is written in Rust and designed for workflows like accessing vault and other machines through serial from a host where SSH is unavailable.

Requirements

• Rust 1.75+
• A serial port such as /dev/ttyUSB0

Install

curl -fsSL https://raw.githubusercontent.com/agoodkind/serial-exec/main/install.sh | sh

If the release asset does not match your platform, run:

cargo install --git https://github.com/agoodkind/serial-exec --locked --bin serial-exec

Configuration

serial-exec reads host definitions from TOML in this order:

1. --host-file
2. SERIAL_EXEC_CONFIG environment variable
3. ~/.config/serial-exec/hosts.toml

Example config:

[hosts.vault]
device = "/dev/ttyUSB0"
baud = 115200
prompt = '(?m)[#$] $'
user = "root"

Usage

serial-exec list
serial-exec ping vault
serial-exec run vault "qm list"
serial-exec run vault "qm list" --json
serial-exec shell vault

Global flags:

• --timeout 30s
• --host-file <path>
• --json

Ctrl-] exits shell mode.

Development

cargo build-native
cargo test-all
cargo clippy-warn
cargo fmt-check

Cargo aliases

Configured in .cargo/config.toml:

cargo build-native
cargo build-aarch64-linux-musl
cargo build-x86_64-linux-musl
cargo test-all
cargo clippy-warn
cargo fmt-check

Cross-compile Linux musl from macOS

For local Linux musl targets on macOS, install the target and LLVM tools and use the rust-lld linker:

rustup target add aarch64-unknown-linux-musl x86_64-unknown-linux-musl
rustup component add llvm-tools

RUSTFLAGS='-C linker=rust-lld -C linker-flavor=ld.lld' \
  CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld \
  cargo build --release --target aarch64-unknown-linux-musl

RUSTFLAGS='-C linker=rust-lld -C linker-flavor=ld.lld' \
  CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld \
  cargo build --release --target x86_64-unknown-linux-musl

You can also call the aliases after exporting the same environment:

RUSTFLAGS='-C linker=rust-lld -C linker-flavor=ld.lld' \
  CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld \
  cargo build-aarch64-linux-musl

RUSTFLAGS='-C linker=rust-lld -C linker-flavor=ld.lld' \
  CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld \
  cargo build-x86_64-linux-musl

This is the same strategy used in the CI release workflow, which currently builds all targets with cargo directly and avoids container-emulation issues.

Release

GitHub Actions builds and publishes:

• serial-exec-linux-arm64
• serial-exec-linux-amd64
• serial-exec-darwin-arm64

Drift-proof context

README.md, .cargo/config.toml, .github/workflows/release.yml, and AGENTS.md are treated as the active coordination points:

• .cargo/config.toml is the source of local command aliases.
• release.yml is the source of build matrix and linker strategy.
• AGENTS.md records agent-facing notes for future changes.

When release targets, artifact names, aliases, or cross-build strategy changes, update the three files (release.yml, AGENTS.md, README.md) at the same time before merging to avoid documentation drift.