Getting Started

Install OpenVesper, configure one LLM provider, and run your first agent. About 10 minutes end-to-end.

Prerequisites

  • Node.js 20 or later. Download from nodejs.org. Verify with node --version.
  • pnpm 9 or later. Install with npm install -g pnpm. Verify with pnpm --version.
  • Git. Pre-installed on most systems. Verify with git --version.
  • One LLM provider key. Anthropic, OpenAI, Groq (free tier), Gemini (free tier), DeepSeek, or run fully local with Ollama.

💡 We use pnpm instead of npm because OpenVesper is a monorepo with 56 packages. pnpm's workspace support is significantly faster.

Step 1 — Install

git clone https://github.com/openvesper/openvesper
cd openvesper

pnpm install
pnpm -r build

First install takes 2–5 minutes (~250 MB of dependencies). Build takes 3–5 minutes (compiles 47 plugins + apps).

If both succeed, you're ready. Verify with:

node apps/cli/dist/index.js --help

You should see the CLI help output.

Step 2 — Configure an LLM provider

OpenVesper reads config from ~/.openvesper/.env. Create it:

mkdir -p ~/.openvesper
cp .env.example ~/.openvesper/.env
nano ~/.openvesper/.env

Set at least one of these:

# Anthropic — recommended for quality
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
OPENAI_API_KEY=sk-...

# Groq — fast and has a free tier
GROQ_API_KEY=gsk_...

# Gemini — Google, free tier available
GEMINI_API_KEY=AIza...

# DeepSeek — cheap for code
DEEPSEEK_API_KEY=...

# Ollama — fully local, no API key needed
OLLAMA_HOST=http://localhost:11434

🔒 Privacy: Your .env stays on your machine. OpenVesper has no servers receiving keys. See Security.

Step 3 — Run your first agent

Ask the default agent something:

node apps/cli/dist/index.js -q "What's the price of BTC?"

That uses the auto agent, which routes the question to the crypto_price tool (CoinGecko, no API key needed) and returns the answer.

Step 4 — Try a specialist agent

The 16 shipped specialist agents are tuned for specific tasks:

# DeFi research
node apps/cli/dist/index.js -a defi-strategist -q "Best stablecoin yields right now?"

# Security review of a folder
node apps/cli/dist/index.js -a security-reviewer -q "Audit packages/plugins/crypto/src/"

# Daily standup helper
node apps/cli/dist/index.js -a productivity-coach -q "Help me run my standup for today"

# Solana program development
node apps/cli/dist/index.js -a solana-dev-coach -q "Set up Anchor 0.31 with Token-2022"

# Workout planning
node apps/cli/dist/index.js -a fitness-trainer -q "Missed leg day. Adjust my week?"

See the full agent catalog for all 16, with per-agent setup guides and example sessions.

Step 5 — Useful CLI commands

# Health check — verifies your install
node apps/cli/dist/index.js doctor

# List all available agents
node apps/cli/dist/index.js --list-agents

# List all loaded tools
node apps/cli/dist/index.js --list-tools

# List all skills (the markdown instructions agents pull in)
node apps/cli/dist/index.js --list-skills

# List configured LLM providers
node apps/cli/dist/index.js --list-providers

# Validate all agent files (checks for missing files, broken references)
node apps/cli/dist/index.js --validate

Step 6 — (Optional) Add a chat channel

Talk to your agents from Telegram, Slack, or Discord instead of the terminal. See:

Step 7 — (Optional) Schedule agents

Run agents on a cron schedule for autonomous mode:

# Daily morning brief at 8 AM
node apps/cli/dist/index.js cron add morning-brief \
  --schedule "0 8 * * *" \
  --agent auto \
  --prompt "Morning brief for {{date}}" \
  --deliver-to "telegram:@me"

# List scheduled jobs
node apps/cli/dist/index.js cron list

See Cron Jobs for full details and Webhooks for event-driven triggers.

Troubleshooting

"pnpm: command not found"

Install pnpm: npm install -g pnpm

"Cannot find module @openvesper/core"

You ran a CLI command before pnpm -r build finished. The build creates dist/ folders that runtime imports require. Re-run pnpm -r build.

"No LLM provider configured"

Set at least one API key in ~/.openvesper/.env. See Step 2 above.

Build fails on a specific plugin

Wipe and reinstall: rm -rf node_modules pnpm-lock.yaml && pnpm install. If it persists, open an issue on GitHub.

What's next?