Security

By default, Telepath communicates over HTTP, meaning that ordinary traffic can be seen in plain text. For authentication specifically, Telepath implements a custom Public Key Infrastructure (PKI) exchange to encrypt device identity during pairing and login. This process is entirely automatic and invisible to the user.

Separate credentials are used for pairing and for an authenticated session, along with locking sessions to the client’s network origin to mitigate unauthorized access.

Access permissions

A paired Telepath client has full management access to the host’s auto-mcs installation. This includes every server managed by that instance, not only the server used during pairing. A client can change settings, read or transfer supported files, manage players and back-ups, install add-ons, and create, edit, and manage amscript.

Telepath does not currently provide read-only clients, per-server access lists, or separate permissions for Console, file operations, and amscript. The host controls are Allow, Restrict, and Unpair.

Caution

A paired client is able to manage amscript, and can execute code on the host with the user permissions of the auto-mcs process. Only pair devices and people you trust with that level of access.

Authentication

Telepath creates a device identity and uses a pairing process to authorize it. After pairing, the host remembers the client for later logins. You don’t need to enter a pair code each time you reconnect. Learn more about pairing here.

There are numerous security features during this process and across subsequent sessions:

Conditional listening	Pair requests are ignored by default, listening must be explicitly enabled on the host
Consecutive pairing	The host generates a unique six-character pairing code that expires after one minute. Three failed submissions invalidate it. Pair requests are tied to the client identity, and must expire before the host will listen for another request
Ephemeral keys	A 2048-bit RSA key pair is generated for a client connection, and the machine-identity value is encrypted with RSA-OAEP/SHA-256 during authentication. These expire after 5 seconds and are discarded after successful decryption
Encrypted storage	Saved authorization records are encrypted on disk using Fernet, derived from the server identity. Note that hardware changes will cause this file to expire
Short-lived sessions	Successful logins issue a signed JWT bearer token with a 30-minute expiration. Expirations are handled seamlessly in the background with automatic logins, granting a new session token
Session validation	Authenticated requests are checked against the active user session and originating IP address for MITM mitigation
Token invalidation	Logout blacklists the current token until it expires; disabled or revoked users are removed from active sessions
Rate limiting	Authentication is rate-limited, including pairing and login endpoints
Threat mitigation	Attempts to subvert sessions, such as MITM attacks, are logged and flush the affected session. This forces reauthentication from the real client. Since logins are automatic, this shouldn’t be noticed by the client

These checks apply to Telepath’s normal authenticated endpoints. A network address alone, or knowledge of a server’s name, isn’t enough to call management actions. Attempts to reuse an expired token, authenticate with invalid credentials, or use an existing session from an unexpected origin are blocked and reported to the audit logger. Sessions are tied to the authenticated client and its originating IP address, rather than allowing a token to be used indiscriminately from another connection.

Transport security

By default, the built-in Telepath host serves HTTP over TCP 7001. The ephemeral key exchange protects the client identity during pairing and login, but it does not encrypt the rest of the HTTP connection. API requests, returned data, file transfers, and subsequent bearer-token headers may be visible to someone who can sniff the host’s network traffic. However, session replays and MITM attacks are explicitly mitigated, and won’t cause noticeable client interruptions.

The client attempts HTTPS when a compatible TLS endpoint is available and will fall back to HTTP for a host that doesn’t provide TLS. HTTPS protects the connection only when properly configured. To use HTTPS, you’ll need to set up a reverse proxy, such as nginx.

Caution

Do not expose the default HTTP API directly to untrusted networks. A private VPN or correctly configured HTTPS endpoint is strongly recommended.

For remote access over the internet, one option is to run a standalone OpenVPN instance on the host’s network and forward the VPN connection instead of the Telepath port itself. If you don’t have a separate system available for a VPN, you can run WireGuard directly on the host machine. Either way, the goal is for the client to reach Telepath through a protected private connection rather than exposing unencrypted API traffic publicly.

A properly configured HTTPS reverse proxy with valid certificate verification is another option, but simply putting Telepath on an internet-facing port doesn’t enable HTTPS.

User restrictions

Restricting a client immediately disconnects its active session and blocks future authentication without removing its saved pairing. This is useful for temporarily blocking access to a known client. Unpairing is the stronger option when a device has been lost, transferred, or should no longer be trusted. Once revoked, the client must complete pairing again to regain access.

Stopping Telepath sharing disables the host API entirely, preventing clients from connecting while it remains disabled.

The same restrictions are available from a headless host. See the Pairing guide for instructions on managing clients from the GUI or headless CLI.

Audit logs

Telepath records all connection and management events in an audit logger, including pairing requests, successful logins, file transfers, server operations, and rejected authentication attempts. Attempts to subvert a live or expired session are blocked and logged by default, giving you a record of suspicious requests, as well as normal client activity. Entries identify the client when available, and can independently distinguish authentication events, warnings, and high-risk operations.

Finding the logs

The audit log directory is inside auto-mcs’s app data, under Logs/telepath. The files are named session-audit_<date>.log and can be found here specifically:

Windows	%APPDATA%\.auto-mcs\Logs\telepath
Linux	~/.auto-mcs/Logs/telepath
macOS	~/Library/Application Support/auto-mcs/Logs/telepath
Docker / headless	The corresponding auto-mcs data directory on the host or persistent container volume, inside Logs/telepath

Open the directory in your file manager or terminal and inspect the .log files with a text editor. You can search for a device name, IP address, endpoint, or phrases such as Potential threat blocked. This is separate from the Minecraft server console and the general application logs.

Audit events first enter an in-memory queue and are written to disk when the logger flushes its buffer. As a result, an event may have been recorded internally before it appears in a log file. Older dated files are pruned according to the app’s log retention limit.

Example log

The following is an example of a real session record:

<< Session Start - Kalebs-MBP.knet.com/kaleb | 192.168.1.141 >>
[11:27:50 PM] [AUTH] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Telepath > Login > Successfully authenticated
[11:27:52 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Main > Open Remote Server > Opened: "telepath is fire"
[11:27:53 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Server: "telepath is fire" > Change Filter > filter_type=everything
[11:27:54 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Server: "telepath is fire" > Java Installed > do_install=False
[11:27:54 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Server: "telepath is fire" > Launch > return_telepath=True
[11:28:01 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Server: "telepath is fire" > Restart
[11:28:02 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Server: "telepath is fire" > Stop
[11:28:03 PM] [INFO] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Server: "telepath is fire" > Kill > timeout=10
[11:28:06 PM] [AUTH] [user: Kalebs-MBP.knet.com/kaleb | 192.168.1.141] Telepath > Logout
-- Session End - Kalebs-MBP.knet.com/kaleb | 192.168.1.141 --

Additional protections

Telepath limits file downloads to recognized auto-mcs directories and supported file types. Upload endpoints also validate filenames to prevent directory traversal. These are safeguards around file transfer, not a replacement for the host-wide trust granted to an authenticated client.

Always keep auto-mcs updated, avoid granting Telepath access to unknown devices, restrict the host’s inbound network access, and use a separate operating-system account with only the permissions needed for your servers. Remember that anyone with full Telepath access can change server content and amscript code.

For security disclosures or feedback, contact help@auto-mcs.com.