___  ___  _  _ __   __ ___  ___
   / __|/ _ \| \| |\ \ / // _ \/ __|
  | (__| (_) | .` | \ V /| (_) \__ \
   \___|\___/|_|\_|  \_/  \___/|___/
     🎈 A S S I S T A N T S

Each assistant is a pre-warmed container that joins a Convos conversation in seconds. It can browse the web, send email and SMS, manage payments, and more.

Launch an assistant · Get Convos

assistants.convos.org          Pool Manager              Railway
┌──────────────┐        ┌──────────────────┐       ┌─────────────┐
│  Pick a      │ claim  │  Pre-warmed      │  run  │  OpenClaw   │
│  template    │───────▶│  instances       │──────▶│  runtime    │
│  or paste    │        │  + providers     │       │  on Convos  │
│  an invite   │        └──────────────────┘       └─────────────┘
└──────────────┘        Railway · OpenRouter         email · SMS
                        AgentMail · Telnyx           payments · web

convos-assistants/
├── runtime/           # Agent harnesses, shared evals, shared .env
│   ├── openclaw/      #   OpenClaw harness (gateway + extensions + skills)
│   ├── hermes/        #   Hermes harness (Python FastAPI + XMTP bridge)
│   └── evals/         #   Shared eval suite (Promptfoo, multi-harness)
├── pool/              # Pool manager + provider services (Express API + Postgres)
├── workers/           # Cloudflare Workers
│   └── credits-sweep/ #   Per-instance OpenRouter credit tracking → PostHog
└── dashboard/         # Playroom — Next.js app at assistants.convos.org

Multi-harness architecture — each harness has its own Dockerfile, deps, and scripts under runtime/. Shared infrastructure (skills, personality, evals, .env, version) lives at the runtime root. Currently: OpenClaw (Node.js, primary) and Hermes (Python, experimental).

Skills — shared across both runtimes:

See runtime/README.md for environment variables, Docker setup, and CI.

Manages pre-warmed assistant instances and all provider integrations. Single Express server, single Postgres database.

starting → idle → claiming → claimed
              ↘ crashed

Instances are created ahead of time. When a user claims one, the pool provisions a Convos conversation on the instance and backfills the pool automatically.

See pool/README.md for API, commands, database schema, and environments.

The Convos Playroom — browse the assistant catalog, launch a new assistant, or invite one into an existing conversation.

See dashboard/README.md for setup, routes, and deployment.

Invite an assistant via the dashboard — visit assistants.convos.org, pick a template, and paste your Convos invite link.

Invite via API — POST /api/pool/claim with an x-api-key header:

{
  "agentName": "tokyo-trip-planner",
  "instructions": "You are a helpful trip planner for Tokyo.",
  "joinUrl": "https://convos.org/v2?i=..."
}

Returns an inviteUrl to share (QR code or deep link). Omit joinUrl to create a new conversation.

Privacy-preserving usage analytics via PostHog. Counts only — no message content, no PII.

Runtimes require POSTHOG_API_KEY and POSTHOG_HOST env vars (forwarded by the pool manager). The credits sweep Worker runs independently — see workers/credits-sweep/.