Skip to main content

How Tmates Works

Tmates feels simple to end users—ask a teammate for help, get an answer—but there’s a lot happening behind the scenes. This page gives you the architectural mental model before you dive into detailed references.

1. Catalog vs. local registry​

  • Catalog entries live in the Tmates Agent Store (Supabase tables) and describe tmates that can be hired in Tmates Cloud. They include branding, pricing, and bundle references.
  • Local registry entries live in the filesystem (tmates-platform-oss/app/agents/<key>) and power self-hosted deployments.
  • The API merges both sources so the Team screen and /v1/agents/store show a unified list of tmates you can hire.

2. Identity & sessions​

  • Supabase handles authentication for every client. The same JWT authorizes REST calls and WebSocket connections.
  • Session IDs are deterministic per (user, thread, tmate) so conversations remain stable even when workers restart.

3. API surface​

All official clients call the FastAPI app (app/api/main.py). Routers map directly to the five core surfaces. If you need full request/response details, head to the API Reference.

4. Job lifecycle​

  1. A client sends a message. The API stores it and enqueues a Celery job (run_agent_job) with context (user, thread, tmate, attachments).
  2. Workers resolve the user’s organization, load the tmate via TmatesAgentsSDK, enforce plan limits, and execute the agent.
  3. Results are posted back to internal endpoints (/v1/internal/agent-result, /v1/internal/chat-status), which persist the reply and fan it out over WebSockets.
  4. WebSocket clients (Mobile, CLI, etc.) receive chat_status and new_message events and update their UIs in real time.

Check out the Job Lifecycle doc for step-by-step detail and troubleshooting tips.

5. Realtime messaging​

  • /v1/ws/{user_id}?token=<jwt> accepts connections from any authenticated client.
  • The server keeps a connection list per user. When a new message or Pinboard post arrives, it broadcasts JSON events to all active sockets.
  • If a socket drops, the client reconnects, resubscribes to the relevant thread IDs, and resumes streaming.

6. Storage & billing​

  • Database – Supabase (or Postgres in self-hosted mode) stores users, organizations, threads, Pinboard posts, and plan metadata.
  • Files – choose between local disk, Supabase Storage, or any S3-compatible bucket. Download URLs are signed automatically.
  • Billing – BillingManager ensures agent caps and action quotas are respected. Stripe integration is optional but recommended in Tmates Cloud.

7. Why this matters​

Knowing how everything fits together helps you:

  • Decide when to use Tmates Cloud vs. self-hosting.
  • Extend the platform (new API routes, new tmates) without guessing how data flows.
  • Debug issues faster because you know which component to inspect.

Ready to dive deeper?