Vruum Agent Setup and Operating Guide

Single source — do not fork. This is the ONE canonical reference for how an AI agent operates Vruum. Downstream surfaces read this file; they do not copy it. The two consumers are:

• llms-full.txt — the served, LLM-ingestible expansion of llms.txt.
• the /docs/agents.md route — the deep Markdown agent reference.

If you are about to paste this content somewhere, wire that surface to read VRUUM_AGENT_SETUP_AND_OPERATING_GUIDE.md instead. A forked copy will drift; a backend drift guard (backend/tests/test_agent_guide_doc.py) fails CI if this doc falls out of sync with the live operating model and the CLI command groups.

This is the customer/agent-facing sibling of the internal contributor guide AGENTS.md. AGENTS.md is for people building Vruum; VRUUM_AGENT_SETUP_AND_OPERATING_GUIDE.md is for agents operating Vruum.

Vruum exposes its full revenue platform — pipeline, people, deals, outreach, marketing, knowledge base — to agents through MCP tools and reusable skills. The CLI is the technical fallback for local setup, CI, local files, and debugging. Both MCP and CLI hit the same authorized backend endpoints under your own token:

1. The vruum CLI — a headless binary with machine-stable --json output on every command. Best for local agent harnesses, CI, and shell pipelines.
2. The MCP server — https://api.vruum.ai/mcp, the full Vruum surface in the AI harness. Best for hosted MCP clients and local harnesses that support remote MCP.
3. Vruum skills — packaged workflow instructions for repeated operating motions such as pipeline fill, outreach triage, engagement triage, and deal review. Skills may be installed directly or bundled by a harness plugin.

Plugins are packaging: when a harness supports them, they should bundle the MCP connection plus Vruum skills so clients do not have to install the CLI.

No surface can exceed your access: every call is authorized server-side by your token exactly as a normal user's would be.

For product truth, read docs/PRODUCT_STATE.md before describing what Vruum can execute. It records current motions, availability boundaries, and retired paths. vruum.md owns direction, not the current capability inventory.

Read this first

If you are an agent, discover the public docs before operating:

https://vruum.ai/llms.txt
https://vruum.ai/llms-full.txt
https://vruum.ai/docs/getting-started.md
https://vruum.ai/docs/mcp.md
https://vruum.ai/docs/plugins.md
https://vruum.ai/docs/skills.md
https://vruum.ai/docs/skills/pipeline-fill.md
https://vruum.ai/docs/cli-reference.md
https://vruum.ai/docs/agents.md

There is one site-level llms.txt and one site-level llms-full.txt. Individual docs pages use .md routes for clean Markdown.

0. Product shape: control panel plus harness

Vruum is not operated from a browser CRM. The web app has four focused jobs:

• Dashboard: observe whether the revenue system is working.
• Relationships: find defensible paths to a person or company, inspect the supporting evidence, and review each introduction action before it happens.
• Docs: learn the harness workflows and hand your agent exact commands.
• Settings: connect providers, manage OAuth, billing, team access, tokens, and company context.

People, accounts, deals, queues, objectives, content, team skills, and tasks are inspected or changed from the agent harness through MCP tools, packaged skills, or technical CLI. The browser renders the Analytics control panel and the approval-gated Relationships workspace, including Stripe-backed revenue truth and relationship evidence, but it is not a general-purpose CRM editor.

If you want a list, ask your agent for the list. If you want a row changed, ask your agent to change it. If you want an explanation, ask your agent to fetch the object and summarize the evidence.

Common first requests:

Give me my daily Vruum briefing.

Show me the people in the CFO objective who replied this week.

Import 50 more manufacturing CFOs into the pipeline and enroll qualified ones.

Review the outreach queue and approve only the drafts that pass the quality bar.

What accounts are expansion-ready, and why?

Show stalled deals and tell me the next action for each.

Show my deal pipelines and stages, then make Enterprise the default pipeline.

Create tasks for every deal that needs a follow-up this week.

Publish this team skill and explain when to invoke it.

Show current MRR and the Stripe evidence behind it.

Draft this week's LinkedIn demand-gen posts from recent objective learnings.

When a request becomes a repeated workflow, invoke the matching skill: vruum-guide, pipeline-fill, outreach-triage, engagement-triage, deal-triage, diagnose-reply, enrich-prospect, expansion-fill, winback-fill, create-content, or the source-specific fill variants.

1. Concepts

Vruum models your revenue engine as a few core objects, a few motions that act on them, and approval queues you steer them through. Learn these once — every skill and tool below operates on them.

You don't run these by hand. You ask your agent in plain language ("show me the people in the CFO objective who replied this week"); under the hood it calls the MCP tools named here. Tool names are examples, not a frozen catalog — confirm the live surface from your harness.

Objects — what Vruum tracks

• Person — an individual contact (a prospect, buyer, or deal stakeholder). The unit of outreach. Ask your agent about one, or read the full picture with get_person_360.
• Relationship path — an evidence-backed route from your OWN LinkedIn, email, meeting, and CRM history to a target person or company. Ask "what's my warm path to X?" and the agent calls read-only find_warm_path. Direct and target-specific verified introductions are kept separate from people worth checking with and same-company entry points; employment alone never proves an introduction. manage_relationship_action carries an approved draft through exact-message review, external-send confirmation, response classification, and outcome history. Nothing is auto-sent. Graph mining is opt-in (network_graph_sync_enabled, metadata only — never message content), and the Relationships workspace has a separate canary rollout gate.
• Account — the company a person belongs to. Carries an account stage (see the lifecycle below) and is where expansion and winback decisions are made. Read and update it with manage_account.
• Deal — an opportunity tied to a person and account. Moves through the tenant's configured pipeline stages and carries an estimated value, stakeholders, and a next step. get_deal_360 returns the full context; fetch type="deal_pipelines" lists pipeline/stage IDs and ordering; and manage_deal creates or moves deals and configures pipelines/stages. When targeting a pipeline during deal creation or moving between pipelines, supply both pipeline_id and stage_id.
• Objective — a targeted cohort plus its messaging plan and goal: the unit you fill with prospects and run outreach into. (Earlier builds called this a "campaign", and before that a "segment".) List with search type="objectives"; read one with fetch type="objective".
• Outreach plan — the per-person multi-touch sequence, enrolled under an objective. It fires due touches on schedule and watches for replies. manage_outreach starts, pauses, and resumes it.
• Touch — one action inside a plan: a specific message, on a specific channel, at a specific time.
• Knowledge base — your uploaded collateral plus connected sources (Drive, Notion, …), retrievable as grounding context for the agent. manage_kb adds and searches it.

Motions — what Vruum does with them

• Diagnose — infer the seller's company profile, offer, ICP, market, and signals from the website and knowledge base. The positioning diagnostic is a narrower cold-outreach viability workflow, not the full product boundary.
• Source and qualify — find prospects through Sales Navigator, CSV, YC, LinkedIn, manual entry, or harness discovery; research them and apply the authoritative backend match gate before enrollment.
• Route relationship paths — inspect the seller's opt-in evidence graph, distinguish verified paths from connector checks and company entry points, and carry an approved ask through one durable action timeline. Vruum never auto-sends the ask.
• Create demand — co-produce and publish organic LinkedIn content, warm active relationships through engagement, optionally amplify approved posts with paid LinkedIn campaigns, and turn qualified own-post engagers into pipeline. Google Ads is metrics-only; paid LinkedIn execution is permission gated.
• Run outreach — execute deterministic multi-touch sequences across email, LinkedIn connection requests, DMs, and InMail. The harness authors message and reply prose; the backend schedules, gates, persists, and sends it.
• Handle inbound and meetings — detect and route email/LinkedIn replies, surface response work, inject Calendly/Cal.com links, and update lifecycle state when meetings book or cancel.
• Manage deals and observe revenue — qualify deals, manage stages and stakeholders, inspect risk, and reconcile exact Stripe-backed MRR, charges, collections, refunds, and disputes. Proposal, signature, and payment execution stay in the customer's existing Stripe workflow.
• Grow accounts — source and run approved expansion and win-back plays. Onboarding and adoption are primarily account-state and impact-tracking surfaces today, not autonomous customer-success programs.
• Learn and operate — diagnose objectives and replies, inspect funnels and outcome patterns, run weekly reviews, synchronize HubSpot, maintain mailbox health, and operate multiple client tenants when authorized.

Read the full motion/status matrix in docs/PRODUCT_STATE.md. It distinguishes executable, assisted, gated, and tracking-only paths and should be consulted before making an availability claim.

Control surfaces — how you steer it

• The three review queues — outreach, engagement, and content work can be reviewed with get_outreach_review / get_engagement_review / get_content_review. Manual outreach requires approval; an objective explicitly configured as full_auto may auto-approve harness-authored outreach under the backend's send and audit guards. Public content and ad spend retain their own explicit approval gates. The deals review is triage, not an approval queue.

• The match gate — when prospects are imported into an objective, a backend quality gate (match score ≥ 70) decides who actually enrolls. Harness pre-filters narrow the list first; the backend gate is authoritative.

• Account lifecycle — every account sits on one of eight stages, which determines the motion that applies:

  Copy snippet

  prospect → engaged → committed → onboarded → adopting → expansion_ready
                                                    (plus: dormant, churned)

  Early stages are outreach territory; expansion_ready triggers the expansion play; churned (with a recoverable loss reason) triggers winback. Move an account with manage_account once the signal is real.

You operate all of this by asking your agent; it calls the MCP tools and skills covered in the sections below. The vruum CLI (§7) is the technical fallback — local setup, CI, local files, and recovery — not the day-to-day surface.

2. Install & set up

Choose the setup path

Use the highest path the harness supports:

1. Plugin: easiest client path; packages MCP plus skills when the harness supports it.
2. Direct MCP: connect the harness to https://api.vruum.ai/mcp and load skills separately if needed.
3. Optional local CLI: technical path for CI, scripting, debugging, local files, or the convenience of vruum init.

Install the CLI only for technical local setup

The CLI requires Node 22 or newer. There is no Brew installer.

npm install -g @vruum/cli
npx @vruum/cli --help

Wire Vruum into your harness — vruum init

vruum init is the one-shot local setup command for technical harnesses. It detects supported AI coding harnesses and configures the shipped pieces for each one:

• Claude Code: registers MCP and installs Vruum skills.
• Codex CLI: registers MCP and installs Vruum skills.
• Cursor, Cline, OpenCode, Windsurf, Gemini CLI: registers MCP when their config is detected; skill placement depends on the harness.

init deliberately does not modify project-level AGENTS.md or CLAUDE.md files. Those files belong to the user's repository; Vruum operating guidance comes from the installed skills and plugin surfaces instead.

The CLI is optional. A direct MCP connection plus the Vruum skills package is a complete setup; use vruum init only when you want the CLI to configure both for you.

vruum login           # store your token first (see Auth below)
vruum init            # wire detected harnesses

init reuses the token from vruum login. Claude Code receives a static Authorization: Bearer MCP config. Codex receives an MCP config that reads the token from VRUUM_MCP_TOKEN at runtime:

export VRUUM_MCP_TOKEN=<your-vruum-token>
codex

Restart your harness afterwards to load the Vruum MCP, then verify with a real tool call.

Manual skill install:

npx --yes @vruum/skills@latest install
npx --yes @vruum/skills@latest install --target /path/to/skills

Restart the harness after installation. On Windows, the skills installer uses directory junctions and does not require Administrator access or Developer Mode.

init is a local-CLI-only command — it writes config files on your host. It is not exposed through MCP.

3. Authentication

vruum authenticates with a personal access token (PAT, vk_live_…). Generate one in the Vruum web app under Settings → API tokens.

# Interactive — prompts for the token (hidden) and stores it in ~/.vruum
vruum login
# Non-interactive — pass it or pipe it in
vruum login --token vk_live_xxx
echo "vk_live_xxx" | vruum login

vruum whoami          # confirm who you are authenticated as
vruum logout          # remove stored credentials

Environment variables

VRUUM_TOKEN makes the CLI fully stateless — ideal for CI and agent harnesses:

VRUUM_TOKEN=vk_live_xxx vruum deal list --json

export VRUUM_MCP_TOKEN=vk_live_xxx
codex

login, logout, init, and the auth commands (whoami aside) are local-CLI only — they manage host credentials/config and are not exposed through MCP.

Multi-company scope — --for-company

Users with access to multiple companies can scope a command to one company:

vruum --for-company <company_id_or_exact_name> deal list

• On the CLI, --for-company is sent as the X-Company-Id header.
• Over MCP, the same intent is the for_company parameter. Resolution is by UUID or case-insensitive EXACT company-name match — partial/substring matches are NOT supported (an ambiguous name raises 400).
• Access is membership-enforced server-side: the value resolves to a user_company_id and the caller's membership in company_users is verified. A 403 means either the value matched no company or the caller is not a member of it. --for-company does not grant access by itself — you get this access by being a member of each company, the same row that grants any normal user access.

4. Calling Vruum from an agent

--json and exit codes

Every CLI command supports --json for stable, scriptable output. Without it, commands print human-readable tables; with it, JSON suitable for jq, agents, and CI.

vruum deal list --json | jq '.deals[] | select(.stage == "negotiation")'
vruum review outreach --json | jq '.items | length'

The process exit code is the agent's success signal:

Global flags

5. The MCP surface

The MCP server at https://api.vruum.ai/mcp exposes supported Vruum workflows as explicit tools. The exact tool set can change as the product changes, so an agent should verify the live surface from the harness instead of relying on a hard-coded catalog in documentation.

After setup, ask the harness to confirm it can see Vruum and run a read-only Vruum check. If the server is missing, rerun setup and restart the harness. If auth fails, confirm the Vruum token or client login used by that harness.

Known Codex CLI issue — resumed threads lose the tool surface. In resumed or long-running Codex threads, the vruum MCP namespace can vanish even though codex mcp list shows it enabled: the model then guesses malformed tool names (for example mcp__vruumsearch) and gets unsupported call, and tool refresh does not bring the namespace back. This is a Codex client bug, not a Vruum server or auth problem (upstream: openai/codex issues #18233, #26196, #25050). Fix on the Codex side: start a fresh thread instead of resuming, or /compact the stuck thread, and keep Codex CLI updated. As a last resort, verify the server directly with npx -y @modelcontextprotocol/inspector --cli npx -y mcp-remote https://api.vruum.ai/mcp --method tools/list.

Use MCP for live reads and writes when the agent already has Vruum tools loaded. Read before writing, summarize evidence before state changes, and make the smallest change that completes the request. Use the local CLI when MCP is unavailable, the task needs a local file, setup/debugging requires host access, or a script needs deterministic stdout and exit codes.

MCP vs local CLI

The MCP server exposes supported workflows as explicit tools. It does not run the CLI server-side. Technical users who need the full command tree should install and run the local vruum CLI in their own harness or terminal.

6. Skills, team skills, and plugins

Skills are reusable workflow instructions loaded by the harness. They are the right surface for repeated operating motions, because the agent can read one small trigger description up front and load the full procedure only when needed.

Vruum ships these skills through @vruum/skills: pipeline sourcing (pipeline-fill, csv-pipeline-fill, sales-nav-deep-fill, yc-pipeline-fill, enrich-prospect), outreach and engagement (outreach-triage, engagement-triage, diagnose-reply), objectives (objective-builder, objective-doctor), deals (deal-triage), account growth (expansion-fill, winback-fill), demand (create-content, demand-gen-loop), meetings (ingest-meetings), evaluation (positioning-diagnostic), and orientation (vruum-guide). The full catalog with one-line descriptions is at https://vruum.ai/docs/skills.

To run a skill, invoke it — /skill-name in a slash-command harness, or ask your agent to run it by name. The bundle installs once via the plugin or npx --yes @vruum/skills@latest install (see §2); after that, there's nothing to set up per skill.

Team skills stored in Vruum are separate from those shipped package skills. Over MCP, the skill facade operates on team skills in the Vruum skills database:

• discover skills with search type="skills";
• read one with fetch type="skill";
• run one with skill action="invoke" id="<skill-name>";
• publish a team skill with skill action="publish" and the full skill Markdown body.

Team skills are playbooks that the team can share. Create and publish them from the harness, not a browser editor: ask the agent to draft the trigger description and body, review it, then publish through the MCP skill tool.

Plugins are packaging. A plugin can bundle MCP configuration, Vruum-shipped skills, agents, hooks, and setup metadata for harnesses that support plugin installation. When a harness supports plugins, Vruum's desired shape is one plugin that installs or configures both MCP and skills. The agent still calls MCP tools at runtime and loads skills as workflow instructions; the plugin makes setup simpler.

7. The vruum command tree

This is the technical CLI reference, not the primary surface — reach for it for local setup (vruum init, login), CI and scripting (--json + exit codes), local-file work (CSV import), and recovery when MCP is unavailable. For day-to-day operation, ask your agent (§8) and let it call the MCP tools.

Run vruum <group> --help for the flags of any subcommand. (Derived from the CLI source — cli/src/commands/*.command.ts — not from a hand-maintained list.)

Soft-delete-only: there is intentionally no deal delete or company delete. Deals retire via deal won / deal lost (revive with deal reopen); companies archive via their account state. History is never hard-removed.

8. Workflows

Opinionated end-to-end recipes for the motions you'll run most. You operate each the same way: say the ask to your agent, and it invokes the matching skill and calls the MCP tools. Each recipe lists the natural-language ask, the skill, the tools it leans on, and how to tell it went well. Need the terminal instead (local files, CI, recovery)? The same motions are in the vruum command tree (§7) and the CLI reference.

Morning triage

When: start of day — see what happened overnight and clear the queues.

Say this to your agent:

Give me my daily Vruum briefing, then review the outreach and engagement queues and approve only the drafts that pass the quality bar.

What runs: the outreach-triage and engagement-triage skills, over get_daily_briefing and the get_outreach_review / get_engagement_review queues, approving through manage_messages / manage_engagements. The skills review each draft against its research and summarize what they changed.

Good looks like: queues at zero, every sent draft personalized and deduplicated across touches, weak drafts edited rather than blanket-approved.

If Gmail already contains scheduled or sent objective email, ask the agent to reconcile that objective before normal triage. It selects the sender mailbox from Vruum channel status, previews exact matches and exceptions, then applies the approved snapshot as external reservations without sending or resending anything. Those rows appear in the externally scheduled count, not the actionable draft queue.

Fill the pipeline

When: an objective needs more qualified prospects.

Say this to your agent:

Import 50 more manufacturing CFOs into the pipeline and enroll the qualified ones.

What runs: the pipeline-fill skill (source variants csv-pipeline-fill, sales-nav-deep-fill, yc-pipeline-fill). It picks a source, deep-researches each candidate, pre-filters against the objective ICP, then lets the backend match gate (≥ 70) decide who enrolls — via import_prospects and research. (CSV import reads a local file, so that one source runs through the CLI; see §7.)

Good looks like: imported prospects are on-ICP and deduplicated, and the qualified ones enroll into the objective — not a raw dump that fails the gate.

Run deal review

When: a pipeline check — find stalled deals and the next action for each.

Say this to your agent:

Show stalled deals and the next action for each, and create a follow-up task for every deal that needs one this week.

What runs: the deal-triage skill, over inspect_pipeline and get_deal_360, updating through manage_deal and creating follow-ups via the tasks tools. It surfaces at-risk deals and fills qualification and stakeholder gaps.

Good looks like: every open deal has a current stage, a named next step, stakeholder coverage, and a dated follow-up task.

To inspect or change the stage model itself, ask the agent to read fetch type="deal_pipelines" first, then use the pipeline/stage actions on manage_deal to create, rename, archive, unarchive, reorder, or set a default. Pipeline and stage IDs are tenant-scoped; a deal move names a valid stage in the destination pipeline.

Diagnose and expand

When: a prospect replied, or a customer is healthy and ripe for more.

Say this to your agent:

Tell me why this prospect replied so we can repeat it — and show me which accounts are expansion-ready and why.

What runs:

• diagnose-reply — what in the outreach earned the reply, so the pattern can be reused.
• expansion-fill — closed-won accounts 60+ days old with no open follow-on, surfaced for an expansion play; manage_account moves one to expansion_ready.
• winback-fill — people who went silent or lost a deal 90+ days ago where the loss reason wasn't "no fit".

Good looks like: wins become repeatable patterns, and healthy or recoverable accounts re-enter outreach instead of going stale.

Generate demand

When: you want inbound, not just outbound.

Say this to your agent:

Draft this week's LinkedIn demand-gen posts from recent objective learnings, in my voice, and schedule them.

What runs: the create-content skill, over manage_content. It pulls your own signal, drafts in your voice, and lets you review before the post is scheduled or published; drafts wait in the content queue.

Good looks like: posts sound like you (not generic AI prose), draw on real results, and land on a consistent cadence.

See also

• AGENTS.md — internal contributor guide (building Vruum, not operating it).
• cli/README.md — the CLI package readme.
• backend/app/mcp/server.py — the live MCP server implementation. The harness should list the current Vruum tools after setup instead of relying on a static tool catalog in this guide.