Deployment Patterns

Single-line summary: Deploy Mentionable as a standalone Node service via @mentionable/node, embed into an existing web framework with one import, or run serverless on Vercel with a Postgres-backed KvStore + cron outbox.

See also: architecture-overview, transport-module-guide, webfinger-agent-card-guide, building-a-connector, glossary

Examples: examples/echo-agent, examples/gmail-echo-agent, examples/gmail-echo-vercel, examples/llm-agent-vercel, examples/embed-{next,express,hono,fastify,node-headless}, examples/slack-connector.

Standalone (Headless @mentionable/node)

The simplest deployment: a Node process that hosts WebFinger, the Agent Card, and the configured Transport modules.

import { createMentionable } from '@mentionable/node'
import { activityPub } from '@mentionable/transport-activitypub'
import { a2a } from '@mentionable/transport-a2a'
import { rest } from '@mentionable/transport-rest'

const mn = createMentionable({
  domain: 'example.com',
  agents: [
    {
      address: '@scheduler@example.com',
      handle: schedulerAgent.handle,
      card: schedulerCard,
    },
  ],
  transports: [activityPub(), a2a(), rest()],
})

mn.listen(3000)

Reference: examples/echo-agent (~30 LOC) and examples/embed-node-headless (~40 LOC).

Embedded (Existing Frameworks)

@mentionable/node exports a request handler you mount under your existing framework. WebFinger goes at the apex, everything else under basePath.

basePath rule (see webfinger-agent-card-guide#basepath): WebFinger is always served at /.well-known/webfinger. Other endpoints (A2A, REST, AP inbox) MAY live under any prefix.

Vercel Serverless

The reference serverless template is examples/llm-agent-vercel — a noncoded full-stack LLM agent: Deploy-to-Vercel → Neon Postgres auto → /setup UI → ready.

Important Vercel-specific gotcha (from feedback_next_bundler_externalize.md): packages with internal this.* dispatch (Fedify, some Postalsys modules) need serverExternalPackages in next.config.js, otherwise Next.js’s bundler silently breaks the dispatch at runtime.

Key Env Vars

The hosting-service embedder pattern (used by llm-agent-vercel) injects OAuth client secrets and Pub/Sub topic IDs from the operator’s GCP, so per-tenant users skip the GCP setup step.

Examples Map

gitagent Mode B

examples/llm-agent-vercel’s /setup accepts a gitagent repo URL. The flow:

1. User pastes repo URL.
2. @mentionable/repo-analyzer reads the repo, produces an AgentProposal.
3. @mentionable/gitagent-mapping maps the proposal into Mentionable address-space + system prompt + tool surface (MCP via @mentionable/mcp-builtins).
4. The deployed agent now answers as that gitagent persona at @<repo>@<vercel-host>.

This is the noncoded path — operators do not write code, they paste a repo URL or a system prompt.

Local Development

pnpm install
pnpm -r run build      # build all packages
pnpm -F examples/echo-agent dev

For Vercel local development with Postgres-backed KvStore: vercel dev with vercel env pull .env.local after linking the project. The vercel:bootstrap skill / omc bootstrap flow handles linking and env provisioning safely.

CI Considerations

Per CLAUDE.md, the build CI matrix (typecheck / test / lint / format:check / e2e-phase1 / e2e-phase2a) MUST be green before merge. Three things break PRs the most:

• Forgetting serverExternalPackages for Fedify in a Next.js example.
• Importing a transport module without including its peer in the consumer package’s dependencies.
• WebFinger mounted under basePath instead of the apex.

Common Mistakes

• Using in-memory KvStore on Vercel. Use @fedify/postgres.
• Letting outbound AP queue persist only in memory. Use a queued outbox + cron.
• Hard-coding the Vercel deployment URL into MENTIONABLE_BASE_URL for previews. Use the per-deployment URL only on prod; previews need preview URLs.
• Not running vercel env pull after adding env vars. Local dev silently uses stale config.
• Skipping the Trusted Connector Issuer policy bootstrap. Even on prod, agents start with deny-by-default for forwarded evidence.