Metadata-Version: 2.4
Name: replx-agent
Version: 2.0.0.post2
Summary: Local MicroPython board-management agent for replx.
License-Expression: MIT
Project-URL: Homepage, https://planxlab.com
Project-URL: Repository, https://github.com/PlanXLab/replx2
Project-URL: Issues, https://github.com/PlanXLab/replx2/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: psutil>=7.2.2
Requires-Dist: esptool<6,>=5.6.0
Requires-Dist: mpy-cross>=1.29.0
Dynamic: license-file


[![PyPI version](https://badge.fury.io/py/replx.svg)](https://badge.fury.io/py/replx)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`replx-agent` is the board-management service used by the `replx` MicroPython CLI. It owns serial discovery and connections, board filesystem operations, transfer staging, and firmware flashing through `esptool`.

## Package Boundary

The CLI depends on `replx-agent`; the agent never imports `replx`. The packages communicate through a versioned TCP RPC protocol, allowing separate builds while protocol versions remain compatible.

## Runtime

- The agent is a single process per endpoint and supports multiple TCP clients using `ThreadingTCPServer` and bounded command worker pools.
- Serial access is owned by the agent. Commands for the same board are serialized; separate boards can be serviced concurrently.
- Client sessions are identified by source IP and terminal SID. `replx agent status` reports all connected clients and their foreground/background board assignments.
- The default endpoint is `127.0.0.1:49153`. The CLI creates `.vscode/.replx` as needed and stores `AGENT_IP` and `AGENT_PORT` there.

## Remote Access

Without `REPLX_AGENT_TOKEN`, the agent listens on `127.0.0.1` and accepts connections only from the same computer. Set `REPLX_AGENT_TOKEN` to the same secret on the agent and every client before starting the agent; with the token set, the default listener accepts network connections on all interfaces. Use `--host <agent-LAN-IP>` to listen on one interface only. The variable name is exactly `REPLX_AGENT_TOKEN` (`REPL_AGENT_TOKEN` is not recognized). The server reads the token at startup, so restart the agent after changing it.

```powershell
$env:REPLX_AGENT_TOKEN = "<shared-secret>"
replx agent start --port 49153
```

The first board command (for example, `replx COM4 ls -r`) can start the agent automatically. On the client computer, set the same token before connecting:

```sh
export REPLX_AGENT_TOKEN="<shared-secret>"
replx agent connect 192.168.1.20
```

The `connect` command defaults to port `49153`; pass `--port 50000` when the agent was started on that port. To limit the listener to one interface, use `replx agent start --host 192.168.1.20 --port 49153`. Ensure the host firewall allows inbound TCP on that port. Do not remove authentication from a network-facing listener: any reachable client could run board commands, modify its filesystem, or flash firmware. The RPC transport is plain TCP, not TLS, so use remote access only on a trusted LAN or VPN and do not expose the port to an untrusted network.

## CLI Lifecycle

```sh
replx agent status
replx agent start --port 49153
replx agent connect 192.168.1.20 --port 49153
replx agent disconnect 192.168.1.30
replx agent stop
```

`agent start` restarts an existing local agent at the selected endpoint. Without `--host`, it listens on loopback when no token is set and on all interfaces when `REPLX_AGENT_TOKEN` is set. `agent connect` verifies the endpoint before saving workspace settings; without `--port`, it checks port `49153`. `agent disconnect IP` removes that client's sessions and releases only boards not still assigned to another client. `agent stop` stops the configured agent and releases its board connections.

## License

MIT
