Metadata-Version: 2.4
Name: usepaxterapp
Version: 0.1.3
Summary: Paxter connector for Hermes — bridges your Hermes agent to the Paxter app over an end-to-end-encrypted relay. Outbound-only: nothing is exposed on your machine.
Author: Paxter
Keywords: hermes,hermes-agent,paxter,plugin,platform,agent
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: paho-mqtt>=1.6
Requires-Dist: pynacl>=1.5

# Paxter connector (Hermes plugin)

Connects your self-hosted [Hermes Agent](https://hermes-agent.nousresearch.com) to the **Paxter** mobile app — privately, with nothing exposed on your machine.

It runs as a Hermes **platform plugin** inside your `hermes gateway`: it dials *out* to the Paxter relay (MQTT over TLS), so there's no inbound port, no public URL, and no tunnel to set up. Works behind NAT, on a VPS, or over SSH/tmux.

## Install

```bash
pip install usepaxterapp
hermes plugins enable paxter
hermes config set platforms.paxter.extra.pairing_code <CODE>   # from the Paxter app
hermes gateway restart
```

`pip install usepaxterapp` pulls the package from PyPI; Hermes auto-discovers it
via the `hermes_agent.plugins` entry point, and `hermes plugins enable paxter`
turns it on. In the Paxter app: **Connect → Hermes** to get your one-time pairing
code. Update later with `pip install --upgrade usepaxterapp`.

## How it works

```
Paxter app → paxter-gateway (backend) → MQTT broker → this plugin → your Hermes agent
```

- The plugin trades the one-time pairing code for a short-lived **JWT** (scoped by the broker to only your own topics) and a broker URL, cached in `~/.hermes/paxter/connection.json`.
- Incoming app messages arrive on `paxter/{userId}/{connectorId}/req`; the plugin dispatches them to your local agent and publishes replies on `.../res`.
- The agent runs on **your** machine and **your** model bill — Paxter never sees your agent's key.

## Security

- Outbound-only: no inbound port is opened.
- The JWT pins this connector to its own two topics — it can never read another user's traffic.
- Revocable from the Paxter app (the backend refuses to re-issue the JWT).

## Files
- `pyproject.toml` — PyPI packaging + the `hermes_agent.plugins` entry point.
- `usepaxterapp/__init__.py` — exposes `register(ctx)` (the plugin entry point).
- `usepaxterapp/adapter.py` — the `BasePlatformAdapter` implementation (MQTT bridge).
