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 (Easy Mode)

On the target machine (the node)

# First run starts a short setup wizard (name, admin, acceptance mode),
# then runs the agent in the foreground:
remctl node start

The wizard asks three things:

1. Node name — a friendly name broadcast on your LAN (e.g. livingroom-pc).
2. Allow admin (exec/shell) commands? — grants the full tier to new controllers, otherwise they get standard (no exec).
3. Acceptance mode for new controllers:
   • auto — trust any controller that connects (easiest, least safe)
   • ask — ask for approval on every connection
   • ask-new — ask only the first time a controller connects (recommended)

You can re-run the wizard any time with remctl node setup, or start without it using the stored config via remctl node start.

On the controlling machine

# Find nodes on the LAN (lists them by name)
remctl ctl scan

# Connect to one by name — this pairs it and makes it the active node
remctl ctl connect livingroom-pc

# Now run actions on the active node
remctl ctl actions list                       # what can I do?
remctl ctl actions status
remctl ctl actions lock
remctl ctl actions shutdown --delay 60
remctl ctl shell "whoami"                      # = actions exec

If you have more than one node, target a specific one with --node:

remctl ctl actions status --node bedroom-pc
remctl ctl nodes                               # list paired nodes + active
remctl ctl forget livingroom-pc                # remove a paired node

Advanced: Manual Two-Way Pairing

If you prefer explicit key exchange (no acceptance-mode prompts), use the original flow. Both sides must still trust each other:

# Node: show its fingerprint
remctl node pair --show
remctl node start

# Controller: pair + show its own fingerprint for the node to trust
remctl ctl pair <node-ip>
remctl ctl pair-show

# Node: trust the controller's public key file
remctl node trust-controller /path/to/controller_identity.pub

Legacy per-command form (still works, defaults to the active node):

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

Security Model (Summary)

• Identity: Ed25519 keypairs generated on first run.
• Authentication: Node accepts controllers per its acceptance mode (auto / ask / ask-new). Default is ask-new — no auto-trust unless you opt in. The manual two-way trust-controller flow still works.
• 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 for new controllers: 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/:

Platform Support

Publishing to PyPI

python -m build
twine upload dist/*

You need a PyPI API token (not your password):

1. Create a free account at https://pypi.org
2. Go to https://pypi.org/manage/account/token/ and generate a token scoped to remctl
3. Copy .env.example to .env and fill in the token, or set these env vars:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

See .env.example for the full list of configurable secrets. No credentials are included in the repository.