Project setup

Every Vendo tool starts as an ordinary repo with a vendo.yaml at its root. This page covers the two-minute version: how the directory is laid out, the smallest manifest that will deploy, and the two choices — language and tool type — that shape every later decision.

Directory layout

A fresh deployment-type tool looks like this:

my-tool/
├── vendo.yaml          # the manifest Vendo reads at deploy time
├── README.md
├── Dockerfile          # deployment tools build a container image
├── src/                # your code
└── tests/

Only vendo.yaml is special to Vendo. Everything else is whatever your language and framework expect. Downloadable and npm tools drop the Dockerfile and add a release/build pipeline appropriate to the platform (PyInstaller, Tauri, npm publish, etc.) — see Tool types below.

The slug in the directory name doesn't matter to Vendo. What matters is name: in vendo.yaml — it becomes the catalog slug, the URL segment, the KV key, and the template filename. Pick it once: lowercase, hyphens, 3–64 chars, matching [a-z][a-z0-9-]{1,62}[a-z0-9]. You can't rename it later without a data migration.

Minimum vendo.yaml

The smallest valid manifest is two lines:

name: my-tool
version: 1

That deploys, but Vendo doesn't know what your tool does. A realistic minimum for a deployment tool that calls an LLM through Vendo's proxy and stores data in Postgres:

name: my-tool
version: 1
runtime: python
integrations:
  - openrouter
env:
  required:
    - DATABASE_URL
health:
  path: /healthz

Every field is optional except name and version. Add what your tool actually needs; leave the rest off. The vendo.yaml subsection walks each field in detail.

Language choice

Vendo ships SDKs for three languages. Pick the one your tool is written in:

• Python — vendo-sdk on PyPI (import name: vendo_sdk). Most existing tools (Hermes, Demo CRM, voicebox). FastAPI / Flask / Django all work.
• TypeScript — @vendodev/sdk on npm. Best for Next.js, Hono, or Express tools that want a single language end-to-end.
• Swift — vendo-sdk-swift for macOS / iOS clients. Used by downloadable desktop tools (openscreen, cap).

The SDK is what reads your runtime env vars, calls the proxy, fetches connection bindings, and verifies inbound webhooks. Use the SDK rather than reading env vars and hitting the proxy directly — the surface is identical across languages, the gotchas aren't.

You don't declare your language anywhere in vendo.yaml. The runtime: field is a hint for the dashboard ("this is a Python tool") but doesn't change build behavior — that's driven by your Dockerfile (deployment), build pipeline (downloadable), or package.json (npm).

Tool types

Vendo runs three kinds of tools. The type is set at the catalog level, not in vendo.yaml, but it dictates what you're shipping:

• deployment — server-side. Vendo provisions a Railway project per tenant, gives each instance a {deployment-slug}.vendo.run subdomain, and runs your container image. Most CRM-, automation-, and bot-style tools are deployments.
• downloadable — a desktop binary. Vendo hosts the artifact at downloads.vendo.run/{slug}/, detects the user's OS, and serves the right build. Use this for tools that need local hardware access (microphone, filesystem, GPU).
• npm — a CLI installed via npm install -g. The dashboard shows the tenant the install + login commands and polls /api/cli/apps until the CLI authenticates.

Most authors start with deployment — it's the path the rest of these docs assume by default. Downloadable and npm tools still use vendo.yaml (for integrations: declarations) but skip the manifest fields specific to server deployments (health:, env:).

Next steps

1. Write your code.
2. Fill in vendo.yaml — start with the manifest overview.
3. When ready, follow Deploy & publish to push your tool to Vendo (privately first, then to the public catalog).