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 three consumers are:

• llms-full.txt — the served, LLM-ingestible expansion of llms.txt.
• the /docs/agents.md route — the deep Markdown agent reference.
• VRU-501 vruum init — the harness instruction emitter (writeInstructions) that wires this doc into a project's AGENTS.md.

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 three jobs:

• Dashboard: observe whether the revenue system is working.
• 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, campaigns, content, team skills, tasks, and proposal creation are inspected or changed from the agent harness through MCP tools, packaged skills, or technical CLI. The browser may still render proof artifacts like dashboards, portal views, and public proposal links, but it is not where day-to-day revenue work happens.

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 campaign 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.

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

Publish this team skill and explain when to invoke it.

Draft a proposal for the Acme deal using the current pricing model.

Draft this week's LinkedIn demand-gen posts from recent campaign 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 campaign 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.
• Warm path — the warmest route from your OWN network (LinkedIn connections, past DMs, email correspondents, CRM history) to a target person or company: a direct relationship, a customer/champion bridge, or a connector employed at the target company. Ask "what's my warm path to X?" — the agent calls find_warm_path and shows named connectors with evidence and an optional intro-ask draft (never auto-sent). Graph mining is opt-in (network_graph_sync_enabled, metadata only — never message content); with it off you still get CRM-derived paths. Enrollment annotates people who have a warm path so you can route to an intro before cold touches.
• 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 pipeline stages (new → … → negotiation → won / lost), and carries an estimated value, stakeholders, and a next step. get_deal_360 for the full context; manage_deal to change it.
• Campaign — a targeted cohort plus its messaging plan: the unit you fill with prospects and run outreach into. (Earlier builds called this a "segment".) List with search type="campaigns"; read one with fetch type="campaign".
• Outreach plan — the per-person multi-touch sequence, enrolled under a campaign. 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 warm paths — inspect the seller's opt-in relationship graph and prefer a defensible introduction path when one exists. Vruum finds the path; it never auto-sends the introduction 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 and close deals — qualify deals, manage stages and stakeholders, inspect risk, draft/send proposals, collect signatures, and collect payment. The deepest close-stack operations are available through REST/UI/CLI rather than the advertised MCP facade.
• 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 campaigns 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; a campaign 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 a campaign, 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. Local CLI setup: technical path for local coding harnesses, technical users, CI, debugging, and local files.

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; skills/instruction placement depends on the harness.

Instruction-file emitters are still deferred in the current adapters. Until they ship, give the harness the install prompt from https://vruum.ai/docs/getting-started or paste the relevant Markdown route into its project instructions.

vruum login           # store your token first (see Auth below)
vruum init            # wire detected harnesses
vruum init --project-dir /path/to/project

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 @vruum/skills install
npx @vruum/skills install --target /path/to/skills

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.

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), campaigns (campaign-builder, campaign-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 @vruum/skills 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.

Fill the pipeline

When: a campaign 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 campaign 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 campaign — 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.

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 campaign 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.