remctl 0.1.0

Secure LAN-based remote PC control and administration

remctl

Secure, LAN-based remote PC control and administration.

remctl lets you control machines on your local network from the command line — lock, shutdown, execute shell commands with streaming output, transfer files, take screenshots, and check system status. All communication is authenticated using Ed25519 keys and encrypted with AES-256-GCM.

⚠️ Intended for your own trusted LAN devices only. remctl is not designed for Internet-facing use. Do not expose it via port forwarding or NAT.

Installation

pip install remctl

From source

# TODO: user adds PyPI API token via env var / twine config before publishing
git clone <repo-url>
cd remctl
pip install -e ".[dev]"

Quick Start: Pairing Walkthrough

remctl requires two-way trust: both the node and the controller must explicitly authorize each other.

On the target machine (the node)

# Show the node's fingerprint
remctl node pair --show

# Start the agent (background via service is recommended)
remctl node start

On the controlling machine

# Discover nodes on the LAN
remctl ctl discover

# Pair with a node (verify the fingerprint before confirming)
remctl ctl pair <node-ip>

# Show your own fingerprint for the node to trust you
remctl ctl pair-show

Back on the node (trust the controller)

# Trust the controller's public key (copy from the controller's output)
remctl node trust-controller /path/to/controller_identity.pub

Send commands

remctl ctl <target> status
remctl ctl <target> lock
remctl ctl <target> exec "whoami"
remctl ctl <target> screenshot -o screenshot.png
remctl ctl <target> push ./file.txt /remote/path/file.txt
remctl ctl <target> pull /remote/log.log ./log.log

Command Reference

Command	Description
remctl node start	Start the node agent in foreground
remctl node install-service	Install as OS service
remctl ctl discover	Discover nodes on LAN
remctl ctl pair <target>	Pair with a node
remctl ctl <target> lock	Lock the remote workstation
remctl ctl <target> shutdown --delay 60	Shutdown with optional delay
remctl ctl <target> restart	Restart
remctl ctl <target> sleep	Sleep/Suspend
remctl ctl <target> logout	Log out current user
remctl ctl <target> closefocused	Close active window
remctl ctl <target> exec <command>	Execute shell command (streamed)
remctl ctl <target> status	Show system status (CPU/mem/disk/uptime)
remctl ctl <target> screenshot -o out.png	Capture screenshot
remctl ctl <target> push <local> <remote>	Push file to node
remctl ctl <target> pull <remote> <local>	Pull file from node
remctl ctl <target> cancel	Cancel pending shutdown/restart

Security Model (Summary)

• Identity: Ed25519 keypairs generated on first run.
• Authentication: Two-way explicit pairing — both sides must trust each other.
• Encryption: X25519 ECDH key exchange → AES-256-GCM, with forward secrecy.
• Replay protection: Per-message sequence numbers + 30-second timestamp window.
• Permission tiers: observe (status/screenshot), standard (commands + files), full (includes exec). Default: standard.
• Audit log: All commands logged unredacted at ~/.remctl/audit.log.

See docs/SECURITY.md for the full threat model.

Configuration

All config files live in ~/.remctl/:

File	Purpose
identity.key	Private key (keep secure)
identity.pub	Public key
known_nodes.json	Paired nodes (ctl side)
known_controllers.json	Trusted controllers (node side)
node_config.json	Node settings (bind address, port, tiers)
audit.log	Command audit log

Platform Support

Platform	Status
Windows	First-class
Linux	Second-class (best-effort)
macOS	Not yet implemented

Publishing to PyPI

python -m build
twine upload dist/*

The user must configure ~/.pypirc or set TWINE_USERNAME/TWINE_PASSWORD environment variables before running twine upload. No credentials are included in this repository.