Self-hosting Tmates

Running Tmates yourself gives you full control over data residency, customization, and release cadence. This guide walks through the open-source tmates-platform-oss stack so you can develop agents, dogfood tmates privately, or deploy them behind your own security perimeter.

Why self-host?

• Develop tmates locally – iterate on manifests, prompts, and tools without touching production workspaces.
• Private/internal use – keep proprietary workflows inside your own infrastructure while still benefiting from the Tmates runtime.
• Customization – swap integrations, add bespoke APIs, or change billing rules without waiting for Tmates Cloud releases.

Architecture recap

Self-hosting gives you the same components as Tmates Cloud, minus the managed services:

• FastAPI app (app/api/main.py) handling REST + WebSockets.
• Celery workers (app/worker/tasks.py) executing tmates.
• Redis as the Celery broker/result backend.
• Postgres/Supabase for persistence (you can use Supabase locally or point at your own Postgres instance).
• Pluggable file storage (local disk, Supabase Storage, S3-compatible buckets).

Prerequisites

Requirement	Notes
Python 3.11+	Use pyenv/asdf to match the runtime used in production.
Redis 7+	Local install or Docker container; required for Celery.
Postgres or Supabase project	Store users, organizations, pinboard posts, etc.
OpenAI / Azure OpenAI credentials	Power built-in tmates like Adam or Nolan.
Stripe account (optional)	Only needed if you want billing enforcement.

1. Clone and configure

git clone https://github.com/<your-org>/tmates-platform-oss.git
cd tmates-platform-oss
cp .env.example .env.local

Edit .env.local with your secrets. Minimum settings:

• ENV=dev
• SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
• OPENAI_API_KEY (or Azure equivalents)
• FILE_STORAGE_BACKEND=local (switch later if you need S3/Supabase Storage)
• CELERY_BROKER_URL=redis://localhost:6379/0

2. Start the stack

Option A – Docker Compose

docker compose -f docker-compose.dev.yml up --build

This spins up the API, worker, and Redis services in one shot. Exposed ports:

• API: http://localhost:8000
• Redis: redis://localhost:6379

Option B – Manual processes

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.api.main:app --reload --host 0.0.0.0 --port 8000
celery -A app.worker.celery_app.celery_app worker --loglevel=info

Run Celery in a second terminal. Make sure Redis is running before starting the worker.

3. Verify everything works

1. Hit http://localhost:8000/health – expect { "status": "ok" }.
2. Call GET http://localhost:8000/docs – confirm the OpenAPI docs load.
3. Run a smoke test:

   WORKER_KEY=adam python run.py agent adam --message "hello" --user-id <supabase_user_id>

   If the agent responds in the terminal, your environment is wired correctly.

4. Managing data & files

• Database migrations – schema files live in app/db. Apply them to your Supabase/Postgres instance as needed.
• File storage – when FILE_STORAGE_BACKEND=local, uploads land under files/users/<id>. Switch to Supabase or S3 by setting the corresponding environment variables (SUPABASE_STORAGE_BUCKET, S3_BUCKET_NAME, etc.).
• Secrets – use .env.local for development and a secrets manager (AWS Secrets Manager, Doppler, etc.) in production.

5. Operating tips

Topic	Recommendations
Logging	Configure LOG_LEVEL and stream logs to your preferred aggregator.
TLS	Terminate HTTPS with nginx/Traefik or a load balancer; point it at the FastAPI app.
Monitoring	Health checks hit /health; add Redis/Postgres monitors to catch outages early.
Backups	Snapshot your database and file storage regularly if you keep long-lived data.
Billing	Leave Stripe env vars blank if you don’t need enforcement. Otherwise, set STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, etc.

6. Customizing tmates

• Add or edit tmates under app/agents/<key>. Each folder contains the manifest, prompts, and tests.
• Use the CLI to run agents locally (python run.py agent <key> --message "test").
• When ready to share, package the agent with your bundle builder and either upload it to your catalog or copy it into another self-hosted instance.

7. Next steps

• Learn how the runtime is wired: How Tmates Works.
• Follow the developer guides: Building tmates and Publishing tmates.
• Keep the Testing & Troubleshooting playbook handy as you operate your deployment.

With those pieces in place, you control the entire Tmates stack—perfect for rapid iteration, private deployments, or building the next generation of tmates.