README.md

Client agent demo

This is a minimal client agent that connects to the control server WebSocket and forwards TCP connections from a local port to the server using a simple message framing protocol. This demo is for prototyping only and not production-ready.

Features

• Connects to control server WebSocket (/ws) and performs handshake
• Supports a simple multiplexing prototype: multiple local connections are assigned short connection IDs and multiplexed over a single WebSocket
• Can forward local TCP connections to the server using a framed protocol
• Offers an optional simple HTTP page response for browser tests (not full HTTP proxy)

Running locally

1. Create virtual environment and install dependencies:

cd client
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Run the client pointing to local server:

python client.py --server ws://localhost:8000/ws --local-port 9000

3. Test with a simple TCP client (keeps connection open):

python test_local_tcp.py

4. For browser test: open http://localhost:9000 — the client will return a simple demo page (prototype only).

Note: For remote HF Space server, use wss://<your-space-host>/ws as the --server URL.