Skip to main content

Publishing tmates

Building a tmate is only half the story—you also need to deliver it to the teams who will use it. This guide covers both distribution paths: the managed Tmates Agent Store and self-hosted catalogs.

1. Version your tmate​

  • Bump the version field in manifest.yaml every time you ship a change.
  • Follow semantic versioning (major.minor.patch) so operators can track compatibility.
  • Include a last_updated date to help workspace admins understand freshness.

2. Create a deterministic bundle​

Even if you plan to ship source code, it’s best practice to package the tmate into a reproducible bundle:

  1. Run your bundle builder (internal script or scripts/publish_agent_bundle.py).
  2. The bundle should include: manifest, code, prompt assets, and any static files.
  3. Store the bundle in your artifact registry (S3, GCS, etc.) and record the URL.

3. Publish to the Tmates Agent Store (Cloud)​

  1. Insert or update the catalog row in Supabase with:
    • key, version, name, description, category.
    • Branding (emoji/color/avatar URL).
    • Bundle URL + checksum.
    • Pricing and plan requirements if applicable.
  2. Mark the status as draft while you test in staging.
  3. Deploy the bundle to the staging environment and run smoke tests via the CLI (tmates chat open <key>).
  4. Flip the status to published when ready. The Team screen and /v1/agents/store will start showing the new version automatically.

Rollbacks​

If something goes wrong:

  • Update the catalog entry to point back to the previous bundle/version.
  • Broadcast a Pinboard post so users know the tmate temporarily reverted.
  • Patch the issue, bump the version, and republish.

4. Publish to self-hosted catalogs​

Self-hosters often curate their own catalog to control which tmates are available internally.

Options:

  • Local registry only – copy the agent folder into app/agents/ and let AgentStore discover it automatically.
  • Custom Supabase tables – mirror the structure of the public catalog but point to internal bundle URLs.
  • Hybrid – keep sensitive tmates local while still pulling public entries from the hosted store.

Document the process for your organization (who approves new tmates, where bundles live, how to roll back).

5. Communicate the release​

Whether you’re publishing to Tmates Cloud or a self-hosted catalog:

  • Post on Pinboard describing what changed, why it matters, and any new environment variables.
  • Update changelogs or internal release notes.
  • Notify workspace admins if the tmate requires additional permissions or billing changes.

6. Monitor & iterate​

  • Watch job metrics and billing usage to ensure the tmate behaves as expected.
  • Add telemetry (Logfire/OpenTelemetry) if you need deeper insight into prompt/tool performance.
  • Gather feedback from the Team Chat threads your tmate participates in and refine the prompt accordingly.

With these steps, your tmate graduates from a local experiment to a discoverable teammate in the Tmates ecosystem. Next stop: monitor it in production and keep iterating.