Ship a CRM tool to the catalog

Pick a slug and lock it in

Your slug is the single name for the tool across every Vendo surface:

• apps_catalog.slug in the database.
• The directory name in vendo-templates/.
• The proxy subdomain (only relevant for adapter-style tools, not deployment-style CRMs).
• The URL segment: vendo.run/tools/<slug>.
• The KV key, the template filename, the docs URL.

Renaming it later is a data migration. Pick once, lowercase, hyphens only, 2–63 characters, matching [a-z][a-z0-9-]{1,62}[a-z0-9]. For a CRM modeled on Twenty, twenty is taken; pick something like <YOUR_TOOL_SLUG> (e.g. mycrm, acme-crm, studio-crm).

A common mistake is making your slug too generic (crm) or too marketing-flavored (acme-crm-2025). Aim for short, unambiguous, and stable: this string will be in URLs your users bookmark for years.

Write the template manifest

The template JSON is what the deploy worker reads to provision a tenant instance. It declares the services to run, the databases to provision, the secrets to mint, the integrations to bind, and the wizard the tenant sees at install time. The schema is documented in Manifest format; below is a CRM-shaped minimum.

{
  "slug": "<YOUR_TOOL_SLUG>",
  "name": "My CRM",
  "version": "1.0.0",
  "services": [
    {
      "name": "server",
      "role": "web",
      "image": "ghcr.io/<YOUR_GH_USERNAME>/<YOUR_TOOL_SLUG>:1.0.0",
      "port": 3000,
      "healthPath": "/healthz",
      "startCommand": "yarn start",
      "env": {
        "DATABASE_URL": "${database_url}",
        "APP_SECRET": "${app_secret}",
        "SERVER_URL": "https://${domain}",
        "STORAGE_S3_ENDPOINT": "${r2_endpoint}",
        "STORAGE_S3_REGION": "auto",
        "STORAGE_S3_NAME": "${r2_bucket}",
        "STORAGE_ACCESS_KEY_ID": "${r2_access_key}",
        "STORAGE_SECRET_ACCESS_KEY": "${r2_secret_key}"
      },
      "volumes": [{ "mountPath": "/data", "sizeGB": 2 }]
    }
  ],
  "databases": [
    { "name": "postgres", "type": "postgresql", "provider": "neon", "region": "aws-us-east-1" }
  ],
  "secrets": {
    "app_secret": { "type": "random_hex", "length": 32 }
  },
  "r2Storage": true,
  "readiness": {
    "healthPath": "/healthz",
    "expectedBootTimeSec": 60,
    "maxRetries": 60,
    "retryIntervalSec": 5
  },
  "integrations": [
    { "provider": "openrouter" }
  ],
  "userInputs": [
    {
      "key": "DEFAULT_LOCALE",
      "category": "user_optional",
      "label": "Default locale",
      "description": "Locale for new accounts (e.g. en-US, fr-FR).",
      "default": "en-US",
      "inputType": "text"
    }
  ],
  "wizardLayout": {
    "version": 1,
    "subSteps": [
      {
        "id": "connect-ai",
        "title": "Connect AI",
        "sections": [
          { "type": "integration", "providers": ["openrouter"] }
        ]
      },
      {
        "id": "configure",
        "title": "Configure",
        "sections": [
          { "type": "wizard_inputs", "groups": ["*"] }
        ]
      }
    ]
  },
  "adminBootstrap": {
    "authMode": "api_seed",
    "seedEndpoint": "/api/seed",
    "payloadTemplate": {
      "email": "${admin_email}",
      "password": "${admin_password}",
      "workspaceName": "${admin_workspace_name}"
    }
  }
}

Things worth knowing about every block:

• services[] runs one Railway container per entry. One service must have role: "web" — that's what the deploy worker exposes on <tenant-slug>-<deployment-slug>.vendo.run. Each service declares its own healthPath; the top-level readiness block configures the boot-time polling loop. Mount a Railway volume for anything your CRM persists outside Postgres (uploads, attachments) and pair it with R2 for cross-deploy durability.
• ${...} placeholders are resolved by the deploy worker during the resolve_env phase. ${database_url}, ${r2_*}, ${app_secret}, ${domain}, ${admin_email}, ${admin_password} are platform-provided. The full list is in Manifest format § Env-var placeholders.
• integrations: [...] lists every provider your tool calls through Vendo's proxy. For a CRM that ships an "AI assistant" feature, openrouter is the canonical choice — it gets you OPENROUTER_API_KEY (a vendo_sk_* proxy key) and OPENROUTER_BASE_URL (https://openrouter-proxy.vendo.run/v1) injected at boot, so an unmodified OpenAI SDK pointed at those env vars meters through Vendo automatically. If your tool calls no third-party providers, set "integrations": [] — empty array, not omitted.
• adminBootstrap.authMode: "api_seed" lets the deploy worker create the admin account by POSTing to a seed endpoint your tool implements. apps_catalog.auth_mode must agree with this value — see the next step.
• wizardLayout controls the multi-sub-step Configure UX (schema in web/src/lib/wizard-layout.ts). It declares version: 1, a subSteps[] array, and per-sub-step sections[] of discriminated types: deployment_name, workspace, admin_credentials, wizard_inputs (with groups: string[]), integration (with providers: string[]), and tool_extras. The ["*"] sweep on groups / providers is the safety net — it picks up any userInputs[] key or integrations[] provider you didn't place explicitly in an earlier sub-step. Leave one sweep in your last sub-step so a forgotten field still renders.

Save the file as <YOUR_TOOL_SLUG>/1.0.0.json in a fork of runvendo/vendo-templates.

Write the catalog seed migration

The apps_catalog row is what makes your tool discoverable. The Vendo monorepo's supabase/migrations/ directory holds the seed migrations; you'll open a PR adding one for your tool.

-- supabase/migrations/NNN_<YOUR_TOOL_SLUG>_tool.sql
BEGIN;

INSERT INTO apps_catalog (
  slug, name, description, tool_type, auth_mode, category, icon_url, marketing, enabled
)
VALUES (
  '<YOUR_TOOL_SLUG>',
  'My CRM',
  'Open-source CRM with the data model of Salesforce, the UX of Notion, and a built-in AI assistant.',
  'deployment',
  'api_seed',
  'productivity',
  '/logos/<YOUR_TOOL_SLUG>.png',
  jsonb_build_object(
    'replaces',     'Salesforce + HubSpot',
    'savings',      '85%',
    'monthlyCost',  '$25',
    'theyCharge',   '$165/mo',
    'pricing',      'credits',
    'featured',     false
  ),
  true
);

COMMIT;

Two things to align before you submit:

• auth_mode and adminBootstrap.authMode must match. The wizard renders different Configure steps based on auth_mode — api_seed, manual_setup, or no_auth. Disagreement causes the wizard to render the wrong step or get stuck in a redirect loop.
• marketing JSONB is what shows up on the catalog card. replaces and savings are the value-prop bullets; monthlyCost and theyCharge are the price comparison. The fields are read by getPublicToolsCatalog in web/src/lib/tools-catalog-server.ts. Set featured: true only if Vendo's team has agreed to feature your tool on the homepage.

Drop the logo PNG into web/public/logos/<YOUR_TOOL_SLUG>.png in the same PR. 256×256 is a safe target; the catalog card renders at 64×64 and the tool page at 96×96.

Write the release migration

A catalog row alone isn't deployable — it needs a tool_releases row pointing at a manifest version. This is the bridge between "the tool exists in the catalog" and "deploys actually work."

-- supabase/migrations/NNN_<YOUR_TOOL_SLUG>_release_1_0_0.sql
BEGIN;

INSERT INTO tool_releases (
  tool_id, source_repo, version, template_version, status, requires
)
SELECT
  ac.id,
  'https://github.com/<YOUR_GH_USERNAME>/<YOUR_TOOL_SLUG>',
  '1.0.0',
  '1.0.0',
  'active',
  '[{"provider": "openrouter"}]'::jsonb
FROM apps_catalog ac
WHERE ac.slug = '<YOUR_TOOL_SLUG>';

COMMIT;

source_repo is metadata only — surfaced on the tool detail page so prospective users can read the code. It doesn't have to be a public repo today, but plan on it being one before the public listing goes live.

Open the templates PR

Push your fork of runvendo/vendo-templates and open a PR against main. The PR body should include:

• What the tool does in one sentence (Vendo's review reads this verbatim and pastes it into the description field if you haven't already).
• Repo URL for the source code.
• Image tag referenced in services[].image — confirm it's pullable without credentials.
• Integrations your manifest declares — confirm each provider slug already exists in packages/integrations/<slug>/integration.ts in the monorepo. If you're introducing a new provider, that's a separate PR first.
• Pricing intent — credits if the tool calls the proxy (any OPENROUTER_* use, any LLM call), free if it's entirely self-hosted.

A GitHub Action — publish-to-r2.yml — runs on every push. It validates the manifest against the schema (required fields, env-var placeholder syntax, userInputs and wizardLayout cross-references) and fails the PR if anything is off. Schema-valid does not mean correct; a human reviewer still checks the substance.

What that reviewer is looking for:

• Slug consistency between manifest, directory name, and seed migration.
• Pullable image. They'll docker pull it from a clean machine.
• Integration coverage. Every integrations[].provider slug must exist in the integrations registry. The reviewer also checks that integrations[] is not silently empty if your tool obviously calls third-party APIs.
• A ["*"] wizard sweep. Missing it is fail-quiet — a forgotten userInputs[] key drops out of the wizard without warning.
• readiness.endpoint actually responds 2xx on a fresh container with no admin seeded.
• Data preservation. Anything that must survive suspend/resume lives in Postgres, R2, KV, or a mounted Railway volume — never in the container filesystem.
• Pricing model matches behavior. pricing: "free" on a tool that calls the proxy silently skips billing. Don't do that.

The reviewer will leave inline comments. Once you've addressed them, the PR merges and the action uploads the manifest to R2 at templates/<YOUR_TOOL_SLUG>/1.0.0.json.

The full reviewer checklist and templates-repo conventions are in Submission and The vendo-templates repo.

Open the monorepo PR

The seed migration and the release migration land together in the Vendo monorepo. The reviewer will sequence the merges so the manifest is live in R2 before the release row points at it.

In your monorepo PR, include the two SQL files from steps 3 and 4, the logo PNG, and a brief description that links back to the templates PR. The Vendo CI runs repo verify --base origin/main on affected packages — if the migrations touch anything beyond apps_catalog and tool_releases, you'll see test failures here.

Verify the listing is live

Once the migration applies, your tool appears at vendo.run/tools/<YOUR_TOOL_SLUG> and in the main catalog. Verify three things:

1. The card renders. Open vendo.run and find the card. Logo, name, replaces line, and monthlyCost should all read correctly. If anything looks off, the marketing JSONB is where to look.
2. The Deploy button works. Click it. The wizard should advance through Connect → Configure → Pay → Launch. Twenty's pattern — one OpenRouter binding then a Configure step — should appear cleanly. If wizardLayout has a bug, you'll see misplaced fields or a missing step here.
3. A real deploy succeeds. Pick a deployment slug, launch, and watch deploy_logs advance from validate_template to notify_user. Common first-deploy failures are:
   • Image pull error — registry credentials weren't wired, or the tag isn't public yet.
   • Healthcheck timeout — your container is up but /healthz doesn't respond within readiness.maxRetries * readiness.retryIntervalSec (the example above is 60 * 5 = 300s). For CRMs with heavy startup work, bump expectedBootTimeSec / maxRetries or add a placeholder healthcheck that returns 2xx immediately and a deeper one for in-cluster orchestration.
   • Admin seed failure — the seedEndpoint in your manifest doesn't match the real route, or the payload schema disagrees.

If anything goes wrong, Logs and debugging and the inspecting-deployment-logs skill cover how to read across the three log surfaces (Supabase deploy_logs, Railway compute, Cloudflare app-proxy).

Cut your next version

You've shipped 1.0.0. The next release is the same shape with two changes:

1. Push <YOUR_TOOL_SLUG>/1.0.1.json to runvendo/vendo-templates, setting previousVersions: ["1.0.0"] so the upgrade path knows the lineage.
2. Open a new release migration that flips the existing active row to inactive and inserts a new active row pointing at 1.0.1 with the integrations array sourced from the new manifest.

The pattern is in Versioning & releases and supabase/migrations/283_hermes_release_3_1_9.sql is the canonical example to copy from. The relevant semver conventions:

• Patch (1.0.0 → 1.0.1) — image rebuild, no manifest shape changes, no new integrations. Safe to roll out to existing tenants en masse.
• Minor (1.0.x → 1.1.0) — additive shape changes (new optional inputs, new optional integrations). Safe with smoke testing.
• Major (1.x.x → 2.0.0) — anything that requires a tenant to re-bind, re-enter inputs, or accept new pricing. Treat as a migration; don't auto-upgrade.

Vendo doesn't enforce semver, but the rollout tooling assumes it. If you ship a breaking change as a patch, automated upgrades will run anyway and break tenants in production.

Existing deployments stay pinned to whatever version they originally deployed against — that snapshot lives in deployments.manifest and never changes unless a human explicitly upgrades the deployment. The full pinning model is in Versioning & releases § Pinning behavior.