Quick Start

This guide gets you from zero to a working Vruum agent session. Start by giving your agent the install prompt below. After Vruum is installed, the Vruum MCP tools and skills carry the operating instructions.

Copy this for your agent

Install Vruum for me.

Read https://vruum.ai/llms.txt, then use the simplest setup path this harness
supports. If Vruum has a plugin here, enable it. Otherwise connect the Vruum
MCP server at https://api.vruum.ai/mcp.

If this is a local coding harness without plugin support, connect the MCP and
install the skills with `npx --yes @vruum/skills@latest install`. Do not install
the Vruum CLI unless I ask for local-file, scripting, CI, or debugging features.

After setup, verify that Vruum MCP tools and Vruum skills are available.

1. Choose the setup path

Use the highest path your harness supports:

You do not need @vruum/cli to use Vruum. An MCP connection plus installed skills is a complete setup. Node is needed only when using the npm skills installer or the optional local CLI; plugin users do not need it.

2. Connect MCP

The Vruum MCP server is:

https://api.vruum.ai/mcp

If your harness supports remote MCP, connect that URL and authenticate with your Vruum account or token according to the harness.

After connecting, ask the harness:

List the Vruum MCP tools you can see, then call get_daily_briefing. If the
Vruum MCP server is missing, tell me which setup step is missing.

Expected client MCP tools include get_daily_briefing, get_next_actions, search, fetch, manage_person, manage_deal, manage_messages, manage_outreach, manage_content, manage_settings, research, import_prospects, and skill.

3. Load skills

Vruum-shipped skills are packaged workflow instructions: pipeline fill, outreach triage, engagement triage, deal review, enrichment, winback, expansion, and content creation. They are separate from team skills saved in Vruum and managed through the MCP skill tool.

If your harness supports plugins, the plugin should bundle MCP plus skills. If your harness exposes a separate skill directory, install the Vruum skills package there:

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

The installer auto-detects Claude Code and Codex. On Windows it uses directory junctions, so it does not require Administrator access or Developer Mode. Restart the harness after installation so it discovers the new skills.

Ask the agent:

List the Vruum-shipped skills available to you, then invoke vruum-guide.

See Plugin, MCP, and Skills for the split between packaging, live tools, and workflow instructions.

4. Optional local CLI

Skip this section for normal Vruum use. Install the CLI only when you need local files such as CSV imports, shell scripting, CI, deterministic exit codes, auth debugging, or the convenience of vruum init. It requires Node 22 or newer.

Install globally:

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

Or run without installing:

npx @vruum/cli --help

Create a Vruum token in Settings -> API tokens. Tokens start with vk_live_. Store it locally:

vruum login
vruum whoami --json

For stateless CI or local agent scripts, skip the stored credential and use an environment variable:

export VRUUM_TOKEN=<your-vruum-token>
vruum whoami --json

Codex MCP uses a separate runtime variable:

export VRUUM_MCP_TOKEN=<your-vruum-token>
codex

VRUUM_TOKEN overrides the stored local credential for CLI calls. VRUUM_MCP_TOKEN is the runtime token Codex reads for MCP. Users with access to multiple companies can scope CLI calls with --for-company <company_id_or_exact_name>; over MCP, use the matching for_company parameter.

Run setup from the project or workspace where you launch your local agent:

vruum init

init detects supported harnesses and configures what each can safely support. Priorities:

• 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 config is detected; skill placement depends on the harness.

init does not alter project-level AGENTS.md or CLAUDE.md files. Vruum operating guidance comes from installed skills and plugin surfaces.

Use CLI Reference for the full local command tree.

5. Restart and verify

Restart the harness so it reloads MCP and skills.

If you installed the optional CLI, you can also verify it locally:

vruum whoami --json
vruum skills list --json
vruum deal list --json

6. First useful workflows

Start with one of these:

Use vruum-guide. Show my live account state, recommend the single next best
action, and hand off to the right specialist skill.

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

Fill pipeline for <segment>. Research fit before import and save only qualified
prospects.

Review active deals, show stalled ones, and update next steps where the evidence
is clear.

What the browser is for

The web app is a read-only window plus configuration. After login, self-serve accounts land on Actions: one ranked work surface built from your daily briefing that folds in pending outreach, new replies, deal alerts, tasks due, and pipeline by stage. Outreach lives on Objectives (/objectives), the list of active and standing plays; each objective's own page (/objectives/[id]) carries Overview, Plan, People, Guardrails, and Learning tabs. Three activity pages give the same read-only view per area — /activity/deals, /activity/accounts, and /activity/people — with a relationship-network lens (?lens=network) on accounts and people.

Beyond that, use the web app for the analytics dashboard, Docs, Settings, integrations, OAuth, billing, team access, API tokens, and public proof artifacts. Do not use it as a CRM workbench. People, accounts, deals, queues, objectives, tasks, team skills, content, and revenue operations are operated through MCP, skills, or the CLI: the web app observes, your agent acts.

The nudge-copy loop

Every row on Actions carries a nudge chip: a ready-made, goal-first prompt for your connected agent. The loop is:

1. Open /actions and scan the ranked actions.
2. Copy the chip on the card that needs attention.
3. Paste it into your connected agent (Claude, Cursor, wherever you connected Vruum).
4. The named skill runs. If your harness doesn't have that skill installed, the prompt already tells the agent to fall back to the underlying MCP tool, so it works either way.

One-line troubleshooting: if the agent says Vruum tools are unauthorized, reconnect Vruum in your harness's MCP settings.

Where to next

• MCP — hosted MCP setup and auth model.
• Plugin — plugin availability and fallback setup by harness.
• Skills — shipped skills, team skills, install paths, and workflow pages.
• CLI Reference — every command group and exit code.