Skip to content
kircheszPublic

About

A peer-to-peer remote control tool.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

krc logo

kirchesz-remote-control

A peer-to-peer tool for running shell commands on a remote host.

Written in Rust Built with iroh Available on Windows Available on Linux

Install

Download a prebuilt binary from the releases page, or build from source:

cargo build --release

For the MCP server (AI agents), see MCP.

Warning

ANTIVIRUS: running a command elevated makes the host self-elevate via a hidden Start-Process -Verb RunAs, a pattern antivirus heuristics often flag — Windows Defender and others may quarantine or delete krc.exe at that point. If you use elevation, add the binary (or run it from an administrator host without the elevated flag) to your antivirus exclusions. This is inherent to a remote-administration tool, not a sign of compromise.

Usage

Commands

# On the host — prints a connection code; keep it running and approve clients:
krc host

# On the client:
krc connect <code> --alias my-laptop

# Identity (ed25519 key, stable across restarts like an SSH host key):
krc identity show      # this machine's endpoint id + key path
krc identity reset     # forget the identity; a new one is generated next run

# Whitelist, while the host is not running:
krc whitelist ls
krc whitelist rm <endpoint-id|fingerprint>

Host

Access modes. When approving a connection the operator chooses: y one-time (in memory, dropped on restart or kick) or Y reusable (persisted to a whitelist, survives restarts until revoked).

Command modes, switchable at runtime from the host console, default accept:

  • accept — the operator confirms every command before it runs.
  • auto — commands run immediately (use once you trust the session).

Console commands:

command action
list show the command mode, active sessions, reusable whitelist and blocklist
mode [auto|accept] show the command mode, or switch it
kick <fp|id> disconnect an active client, drop its access and add it to the blocklist
unblock <fp|id> remove a client from the blocklist
help list console commands
quit / exit shut the host down

<fp|id> is the client's short fingerprint (as shown by list) or full endpoint id.

Client

In the REPL: cd <dir> sets the working directory, !<command> runs elevated, Ctrl+C cancels the running command, exit / Ctrl+D quits.

Configuration

State lives in the OS data directory (%APPDATA%\krc on Windows, ~/.local/share/krc on Linux); override with --data-dir <DIR>. An optional config.toml there tunes behaviour (all keys optional):

shell = "powershell"        # command shell; default powershell (Windows) / sh (Unix)
command_timeout_secs = 0    # per-command timeout; 0 disables
approval_timeout_secs = 60  # auto-deny if the operator is silent; 0 waits forever
connect_rate_per_min = 20   # max connection attempts per client per minute; 0 unlimited
exec_mode = "accept"        # "accept" (confirm each command) or "auto" (run immediately)

Alongside it the host keeps whitelist.toml, blocklist.toml, and an append-only audit.log (one JSON object per line: approvals, denials, kicks, commands, exits).

Scripting (NDJSON)

To drive the client from scripts, run krc connect <code> --json: one JSON request per line on stdin, one JSON event per line on stdout.

  • Requests: exec (command, cwd?, id?, elevated?), cancel (id), put (path, src, id?), get (path, dst, id?).
  • Events (tagged with the request id): granted / denied, started, stdout / stderr, exited, file_done, error, kicked.

Several commands may run at once.

MCP

Install

Ask your AI agent:

Install the krc MCP server from https://github.com/kirchesz/krc

AI agents: follow mcp/INSTALL.md step by step.

Manual setup and client config examples: mcp/README.md.

Usage

Run krc host on the machine to control and give the agent the connection code it prints. The agent connects and runs commands; you approve them in the host console.

Development

cargo build
cargo run -p krc -- host

Requirements

  • Rust 1.91+ (iroh 1.x).
  • Bun (for the MCP server in mcp/).
  • Windows: the MSVC toolchain, so the app icon can be embedded (optional — the build still succeeds without a resource compiler).

Workspace layout

crate role
krc-proto wire messages + (de)serialization (transport-agnostic)
krc-transport iroh endpoint, tickets, stream framing
krc-host host role: accept loop + protocol handling
krc-client client role: REPL + NDJSON session drivers
krc the krc binary (CLI wiring both roles)

License

Released under the MIT License.

About

A peer-to-peer remote control tool.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages