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.

Chat requests remain backward compatible. The phone may add languageTag in the app-supported locale subset: en, de, or es, with an optional script and region such as es-MX or es-Latn-419. A normal user message may also add a bounded clientMessageId; an exact retry returns the original row, while reusing that id for different data conflicts. A tapped smart reply sends its ordinary content plus clientMessageId, selectedReplyId, and the assistant inReplyToSeq. The server accepts it atomically only when it matches the newest visible assistant choice and has not already been consumed. Old clients may omit all optional metadata. Chat responses omit metadata when it is absent.

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.

write_chat_reply may attach up to four suggestedReplies. Each choice is an object with a stable lowercase id, a short localized label, and the normal chat message submitted when tapped. The server validates, bounds, and stores these choices. URLs and shell/command-like content are rejected. The same nutrition, hydration, supplement, weight, and body-composition boundary applies to both labels and submitted messages.

An athlete_setup_draft.v1 always represents one four-week mission: goals.blockWeeks is 4, coachingStyle is exactly Straight, Hype, or Calm, and goals.successTest contains two or three measurable checks joined with normalized ; separators.

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.