Agent install playbook

​

Start here

1. Detect the stack. Read package.json. A next dependency means Next.js; an express dependency means Express. Anything else — Cloudflare Workers, Bun, Deno, Hono, Fastify, Lambda, bare Node — is the third scaffolded path: pass --framework custom in step 3 and init writes a runtime-neutral vendo/server.ts exporting handleVendoRequest(request, env), which your runtime mounts in one line (Edge runtimes). Workspace repos: pick the app package first. A root package.json with a workspaces field — or a pnpm-workspace.yaml that declares a packages: list — means the framework dependency lives in an app package (apps/web, packages/app, …), not at the root — and detection reads the package.json of the directory init targets. Run at the root of a workspace repo and detection finds no framework: init errors non-interactively, or lands on the runtime-neutral custom scaffold a Next or Express app should not get. Choose the app package now; the install in step 2 targets it, and every later command runs in (or is pointed at) that directory. Read that file before you believe it. Under pnpm 10 pnpm-workspace.yaml is also where plain settings live — onlyBuiltDependencies, minimumReleaseAge, the exclude list in step 2 — so a copy with no packages: key is an ordinary single-app repo, and treating it as a monorepo sends you hunting for an app package that does not exist.
2. Install the package, then verify what actually resolved.
   npm install @vendoai/vendo
   npx vendo --version   # must be >= 0.29.0
   
   In a workspace repo, install into the app package with the host’s own package manager instead — a plain root npm install fights the workspace lockfile:
   npm install @vendoai/vendo --workspace apps/web   # npm workspaces
   yarn workspace <app-package-name> add @vendoai/vendo
   pnpm --filter <app-package-name> add @vendoai/vendo
   
   Then run the version check — and every npx vendo … step below — from that same app directory. On pnpm only: the install downloads everything and then exits 1 with Ignored build scripts: @mongodb-js/zstd, esbuild, node-liblzma. None of the three needs compiling. pnpm writes the names into pnpm-workspace.yaml with a placeholder — set all three to false and install again. Do NOT run pnpm approve-builds (it is interactive) or allow all builds.
   # pnpm-workspace.yaml
   allowBuilds:
     '@mongodb-js/zstd': false
     esbuild: false
     node-liblzma: false
   
   ONE package, and no others. @vendoai/vendo is the umbrella: it carries every @vendoai/vendo/* subpath the files init writes import, and it puts the vendo binary into node_modules/.bin — which is what the version check above and the predev/prebuild hooks init adds to package.json run. vendoai is a thin ALIAS of it, for npx vendoai@latest … before anything is installed; as a dependency it adds nothing, and installing it INSTEAD of the umbrella is the shape that breaks — pnpm’s strict node_modules cannot resolve @vendoai/vendo/* through an alias, so every route 500s with Module not found: Can't resolve '@vendoai/vendo/server'. The version check is not optional: stale placeholder versions (0.1.x) exist on npm, and package managers with a release-age cooldown (pnpm 11 holds new releases for a day by default via minimumReleaseAge; npm’s min-release-age is opt-in) will SILENTLY resolve a fresh Vendo release to that stale version — or to nothing. Everything this playbook uses (init --agent, vendo login, sync --ai) does not exist there. If the version is old or missing, exclude Vendo from the cooldown and reinstall:
   # pnpm-workspace.yaml
   minimumReleaseAgeExclude:
     - vendoai
     - "@vendoai/*"
   
   (npm: unset min-release-age for this install, or pin the exact latest version.) Re-run the version check before continuing. Upgrading instead of installing fresh? If the repo carries a direct @vendoai/vendo dependency next to the vendoai alias (common in 0.4.1-era installs), bump BOTH to the same version — bumping vendoai alone half-upgrades: new CLI, old runtime.
3. Run init in agent mode and relay its questions. Init asks; you carry the questions to your human and their answers back. Both commands below run from the app package directory (step 1’s pick). vendo init can also be pointed at it from the root (npx vendo init apps/web), but vendo login writes the minted key to .env.local in the directory it runs from — a login at a workspace root lands the key where the framework never loads it, and everything afterward silently behaves keyless.
   npx vendo init --agent
   
   That run writes nothing and exits 0. It prints ONE JSON object holding the questions init still needs answered, each with its options, its recommended pick, and the flag that answers it. Put all of them to your human in your very next message, in your own words, in one turn. Keep init’s order and keep its recommendation first: “recommended” in the label is not enough if the cursor lands on the other choice. Usually there are four. How will people use your agent: embedded in their app (most apps, and the recommended pick), through their own agent loop, or from outside AI apps over MCP. Should the assistant act as their signed-in user, on the provider init detected (which preset?). Where the model comes from: a free Vendo Cloud key is one browser click and needs no provider account, or they bring their own Anthropic or OpenAI key. And where their app runs in dev — init prefills the port their dev script names, so this one is usually a yes, and the answer lands in .env.local as VENDO_BASE_URL. Say what each option gets their users, not what it configures. One more consent gate rides ahead of the grading pass: that pass spends model tokens, so init asks before it runs. Relay it like the rest — the answer is money, and it is not yours to give. Take the model answer first, before you re-run anything. It is the one answer that has no flag: the Vendo Cloud pick is a login you run now, and the key only counts once login has written it to .env.local. If they choose Vendo Cloud, drive the login as a bounded loop — never a single blocking call:
   npx vendo login --wait 90
   
   Run this step ALONE — never batched in parallel with other commands — and the moment the URL and code print, STOP and put both in your very next message to your human: they cannot see your shell. Do not start other work until you have relayed them. Run it BARE — never pass --email, a positional email, or any identity hint. You do not know which account your human wants; they sign in as whoever they choose on the approval page, and a guessed hint (from git config or anywhere else) is an assumption, not a fact. The first run prints an approval URL and code; relay both to your human so they approve in the browser. Then re-run vendo login --wait 90 in a loop until it reports the key landed in .env.local. Each re-run resumes the SAME request — no new code, no duplicate key — so the human’s approval lands whenever it arrives. Never background this command and never wrap it in a shorter timeout: a 90s bounded call returns on its own; a killed call is why you loop. The credential is delivered straight to the CLI (no email OTP, and no key ever transits your transcript; the raw protocol is auth.md). If they bring a provider key, never assume it exists — ask where it is set. Now re-run init with their answers as flags. That run writes:
   npx vendo init --agent --use-case embedded --auth clerk --byo
   
   status tells you which run you got: the questions, or the write. Every answer on the first call skips the ask pass and writes in one go, which is right only when your human has already told you everything. --use-case takes embedded, agent-loop, or mcp. --auth takes authJs, clerk, supabase, auth0, jwt, or none. --byo means your human brings their own model key; --cloud-key <key> answers with an existing Vendo Cloud key. A VENDO_API_KEY already sitting in .env.local needs neither: init merges it into the run’s env, uses it as it is, and never asks. If they bring their own key, tell them to put it in .env.local as ANTHROPIC_API_KEY=... or OPENAI_API_KEY=... and to tell you when it is there. It never passes through your chat. --framework <next|express|custom> matters when detection fails: agent mode does NOT stop to ask, it falls through to custom. So a Next or Express host whose package.json you could not read is a runtime-neutral scaffold nobody asked for — pass the flag yourself whenever step 1 left you unsure. See the CLI reference for every other flag and vendo init for exactly what it writes.
4. Take the Continue link. The write run prints no code and no steps. It ends on four computed lines and one URL — what it wired, what it detected, the guard posture it left you, and where to go next:
   Wired: .env.example, .vendo/install.json, …, lib/vendo.ts, next.config.mjs
   Detected: Next.js · no auth detected · npm · port 3000
   Guard: writes run without approval — how to tighten: vendo.run/agents.md
   Continue: https://docs.vendo.run/product/quickstart
   
   The receipt carries the same as structured fields (wrote, detected, guardPosture, continueUrl). That Continue URL is your section below, and its section names the one page to fetch:

   Continue link	Your section
   /product/quickstart	In the product
   /existing-agent/ai-sdk or /existing-agent/mastra	In an agent you already run
   /outside-agents/quickstart	Outside agents over MCP

   One link, one section, one page. If init named a path your human did not expect, that is a question for them, not a second install. Nothing in that tail is a paste: init writes the files itself and the code lives on the pages below. A backend agent takes none of this. That path needs no CLI and no init — see In the backend, which starts from an empty project rather than from a Continue link.

​

Next.js: serverExternalPackages

serverExternalPackages: ["esbuild", "@electric-sql/pglite"],

​

What every path shares

guard: guard({ policy: "cautious" }),

npx vendo sync --ai

• Tool descriptions. Write each extracted tool as the task a user would ask for, not the endpoint it calls.
• Risk grades. Anything destructive or irreversible that grading missed gets confirmEach in .vendo/overrides.json, the file that means “a human decided this” and that sync never clobbers.
• The product brief. Replace the .vendo/brief.md placeholder with what this product does and for whom, read out of the code.
• Theme slots. Fill anything .vendo/theme.json left unresolved from the app’s own styles.

​

In the product

import { VendoProvider, VendoOverlay } from "@vendoai/vendo/react";
import theme from "../.vendo/theme.json";

<VendoProvider baseUrl="/api/vendo" theme={theme}>
  {children}
  <VendoOverlay />
</VendoProvider>

import { VendoSlot } from "@vendoai/vendo/react";

<VendoSlot
  id="home-hero"
  label="Dashboard hero"
  description="main dashboard area, where users keep KPI views"
>
  <YourOriginalCard />
</VendoSlot>

​

In an agent you already run

• AI SDK loop → https://docs.vendo.run/existing-agent/ai-sdk.md
• Mastra loop → https://docs.vendo.run/existing-agent/mastra.md

export const resolvePrincipal = (req: Request) => auth.principal(req);

​

Outside agents over MCP

npx vendo init --agent --use-case mcp --auth authJs --base-url http://localhost:3000

1. mcp: true plus the OAuth adapter. The door mints its own principals through a HostOAuthAdapter, and createVendo THROWS at composition without one. auth is the one door that holds it: hand it a preset, or hand it the object a preset returns and write the members yourself — oauth is a member either way. Every named preset fills it, so --auth authJs|clerk|supabase|auth0 (or jwt({ secret })) is the whole answer; --auth none is NOT — it writes auth: { principal } and no oauth member, so the door stays shut until that member is filled. Which preset: host auth.
   export const vendo = createVendo({
     auth: authJs(), // supplies principal, actAs, and the door's oauth half
     mcp: true,
   });
   
   No login yet? No preset applies — there is no session to read, and installing a provider’s SDK is not a login. Write the two members yourself, in the same auth object --auth none already wrote: keep its demo principal, and add an oauth whose session hands the door that same subject instead of bouncing a browser — the door still renders its own consent page.
   export const vendo = createVendo({
     auth: {
       principal: async () => ({ kind: "user", subject: "demo-user" }),
       oauth: {
         session: async () => ({ subject: "demo-user" }),
         principal: async (subject) => ({ kind: "user", subject }),
       },
     },
     mcp: true,
   });
   
   Leave actAs out. A stub returning empty headers is worse than an absent seam, because a fixed demo principal can never act as anyone else. The price of leaving it out is that the host’s own route-bound tools answer not-implemented over the door, while vendo_make and the apps tools work. Every client acts as that one person: a demo or an internal tool, not a multi-user product. Server-action-bound tools answer not-implemented over MCP whatever actAs says — they execute in-process with the present user’s session, and a door call has none. Top-level principal, actAs, and oauth are the deprecated spelling of those same members, and memberships has a top-level spelling too: each still works alone, but pass any of the four beside auth and createVendo throws naming the mixed keys.
2. The discovery route. The door’s discovery documents live at ORIGIN-ROOT paths, outside /api/vendo, so the catch-all route never sees them and that directory needs a handler of its own:
   // app/.well-known/[...vendo]/route.ts (src/app when the repo uses it)
   import { wellKnownVendoHandler } from "@vendoai/vendo/server";
   import { vendo } from "@/lib/vendo"; // wherever init put the composition
   
   export const { GET, POST } = wellKnownVendoHandler(vendo);
   
   The handler answers only the door’s own paths and 404s everything else under /.well-known. An Express host instead mounts the mountVendo() that init generated into its own vendo/server.ts at the origin root as well (app.use("/.well-known", mountVendo())) — registered AFTER the app’s own well-known routes, because that middleware is terminal: anything behind it gets Vendo’s not-found JSON. Custom runtimes route /.well-known into the same handleVendoRequest(request, env) they already export.
3. VENDO_BASE_URL. It names the origin the door actually answers on: the dev origin while your human is local, the deployment’s FULL public URL (path prefix included) in production. The issuer, every advertised endpoint, the protected-resource identifier, and the RFC 8707 audience all derive from it; left unset they come from the request URL — behind any proxy the proxy-internal origin, so discovery advertises endpoints no client can reach. Forwarded headers are never consulted.
   .env.local

   VENDO_BASE_URL=http://localhost:3000
   
   Init’s dev-URL question already wrote that line (--base-url is the same answer as a flag). Production is set where the host DEPLOYS — in the platform’s own environment settings, never in a committed file — and that one stays your human’s (E-MCP-009).
4. serviceAuth — only when asked for. Skip it unless the HOST’s own backend has to act for a user who is not at a browser (a nightly job, a queue worker). mcp: { serviceAuth: { keys: [...] } } opens an RFC 8693 exchange at the door’s own token endpoint: the backend posts a key plus one of the host’s user ids and gets back a short-lived token bound to that user. The keys are opaque secrets your human generates — ask before creating one. On the MCP init path a local door generates one into .env.local and wires it by DEFAULT, which is also what keeps sign-in on the dev machine; a broker-fronted door (--posture broker) serves no token endpoint of its own, so the key is the console’s to create there. Third-party agents need none of it; they run the per-user OAuth the door already serves. Recipe: MCP door.

​

In the backend

npm install @vendoai/vendo ai zod

• chat(message) is one turn and the answer, with no route and no stream in the way.
• handler() is the whole agent as one fetch handler — the chat turn, the thread list and transcript, and the approvals wire — mounted on one catch-all route.
• run(task) is work nobody is watching.

​

Rules of engagement

• Ask your human before creating any account or key. That includes Vendo Cloud (vendo login), model provider keys, and sandbox accounts (E2B or the managed Cloud sandbox). Relay the choice; never sign up on your own. Look before you ask, though: a VENDO_API_KEY already in .env.local or the environment is used as it is, so there is no key to create and nothing to ask.
• Never invent props or tools outside the catalog. Only components registered in vendo/registry.tsx exist, and only with the props their schemas declare. Only tools in .vendo/tools.json exist. Copy real names from source; see tools and catalog.
• Run vendo init before touching .vendo/. Init writes the whole .vendo/ contract (tools.json, overrides.json, policy.json, brief.md, theme.json) itself, and the AI grading pass writes judgments.json beside them. Don’t author or edit any of those files before the first init run; re-run npx vendo init instead of hand-writing scaffold files (the route, the registry skeleton, .vendo/ contents). judgments.json is a LAYER, never a copy: each entry is keyed by tool name and applied on top of that tool’s tools.json entry (description, title, risk, and the rest), with overrides.json — the human layer — winning last.
• The star ask acts only on an explicit yes. Your prompt ends by asking your human whether to star the repo. If they say yes and the GitHub CLI is authenticated, run gh api --method PUT /user/starred/runvendo/vendo; otherwise print the star link from your prompt (fallback: https://vendo.run/star?src=agent) for them to click. If they say no or don’t answer, drop it — never star on their behalf without that yes.

​

The leaves

• Host auth: detect the host’s auth provider, wire the right preset, know when to ask the human.
• API tools: expose the host API as tools, and what the extractor reads to find them.
• Troubleshooting: every doctor error code: symptom, cause, exact fix.

​

Agent surfaces reference