t4l-server

t4l-server is the small trusted bridge between one T4L Trainer phone and one host-owned OpenClaw coach.

It does four jobs:

1. Pair the phone through an authenticated owner channel.
2. Verify every phone request with an Ed25519 device proof.
3. Store phone-accepted state, chat, and reviewable agent results in SQLite.
4. Expose the same data to the coach through MCP.

It does not install or manage OpenClaw. It does not accept model keys from the phone. It does not expose its MCP key to the phone.

The whole system

authenticated owner channel
          |
          | confirms XXXX-XXXX on the host
          v
phone -- signed HTTPS --> t4l-server <-- host-only MCP key -- OpenClaw coach
                              |
                              v
                           SQLite

Run one isolated server and one OpenClaw coach per athlete. Put the public phone routes behind trusted HTTPS. Keep the channel-confirmation and MCP calls on the host.

Install

Python 3.11 or newer is required.

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

Run

Set two host-only secrets:

• MCP_T4L_API_KEY: used only by OpenClaw for POST /mcp.
• T4L_CONNECTOR_RUNTIME_TOKEN: used only by the authenticated owner-channel adapter to confirm pairing.

Then start the server:

export MCP_T4L_API_KEY='replace-with-a-long-random-secret'
export T4L_CONNECTOR_RUNTIME_TOKEN='replace-with-another-long-random-secret'

t4l-server serve \
  --data-dir /var/lib/t4l/coach-tobi \
  --host 127.0.0.1 \
  --port 8787 \
  --api-key "$MCP_T4L_API_KEY" \
  --agent-id coach-tobi \
  --agent-name "T4L Gym Bro" \
  --agent-runtime openclaw \
  --connector-owner-id 'slack:workspace-id:user-id' \
  --require-https

Bind locally and publish it through a trusted HTTPS reverse proxy. If the proxy terminates TLS, it must send Forwarded: proto=https or X-Forwarded-Proto: https.

The owner identity format is exactly channel:account:sender. Repeat --connector-owner-id if the coach has more than one authenticated owner channel.

Pairing

The normal first launch has one input: the connector address.

1. The phone reads /.well-known/t4l-agent.
2. It creates an Ed25519 device key and calls POST /v1/pairing/requests.
3. It shows /t4l connect XXXX-XXXX.
4. The user sends that command through the authenticated owner channel.
5. The host adapter calls POST /v1/pairing/channel-confirmation with its runtime token and verified channel identity.
6. The phone signs the challenge and calls POST /v1/pairing/complete.

The returned token is bound to that device key and has only chat, sync, and status scopes. Every later app request signs the token id, device id, timestamp, nonce, method, exact path, and SHA-256 body hash.

Pairing fails closed when the runtime token or owner list is missing.

Phone API

Public discovery and pairing:

Signed phone routes:

The app publishes one atomic v2 bundle. Its only context kind is accepted_state. A fresh accepted setup may also contain exactly one training_block_request.

The only phone-review results are:

• athlete_setup_draft
• training_block_plan

A result stays pending until the phone acknowledges its exact resultId and revision. Importing a training block is always an explicit user action.

MCP API

POST /mcp accepts the host-only API key through Authorization: Bearer ... or x-t4l-token.

The coach can:

• read the accepted state and current block request;
• read recent chat and standing coaching notes;
• reply in chat;
• write a pending athlete setup draft;
• write a pending training block plan.

It cannot write accepted phone state. It cannot install software. It cannot create nutrition, hydration, supplement, weight, or body-composition prescriptions. The server blocks those topics in agent output and strips old nutrition fields before they can re-enter a coach prompt.

State ownership

The phone is the source of truth.

• Server context is a copy of phone-accepted state.
• Agent writes are pending proposals.
• The phone validates and accepts or rejects them.
• Daily workout choice is local and deterministic.
• The active workout uses the frozen phone session snapshot.
• Apple Watch owns progress while it controls the session.

Development

.venv/bin/ruff check .
.venv/bin/mypy
.venv/bin/pytest -q

The production phone uses device-bound proofs. The production coach uses MCP from the host.