15-Minute Quickstart

This guide gets you from nothing to a running Manasvi agent — with a real model and a real first message — in about 15 minutes.

We'll use Ollama (free, runs locally, no API key) and the terminal chat interface. If you want to use OpenAI, Claude, or connect Telegram instead, you can do those steps after the initial setup.

What you'll need

Before starting, make sure you have:

Node.js 20 or newer — check with node --version
pnpm — check with pnpm --version (install with corepack enable)
Git — check with git --version
Ollama — download from ollama.com (free, takes ~2 minutes)

If you're missing any of these, see Prerequisites for install instructions.

Skip Ollama for now

If you don't want to install Ollama yet, you can use mock mode — it gives predictable test responses without connecting to any AI. You'll still see the full pipeline working.

One-command setup

If you want a single guided flow instead of the steps below, run pnpm manasvi setup after installing dependencies — it detects init state, walks you through model and channel selection, and runs doctor. Use --profile demo for a zero-config local start.

Step 1 — Get Ollama ready (5 min)

If you're using Ollama, do this first:

# Start Ollama
ollama serve

In a separate terminal, pull a model:

# Llama 3.2 (3B) — fast, works on most laptops with 8GB RAM
ollama pull llama3.2

This downloads about 2GB. It only happens once.

What is Ollama? It's a tool that runs AI models locally on your computer. Once you've pulled a model, everything happens on your machine — no internet connection needed, no API costs.

Step 2 — Download Manasvi (1 min)

git clone https://github.com/nishchay7pixels/manasvi.git
cd manasvi
corepack enable
pnpm install

Step 3 — Initialize (1 min)

pnpm manasvi init

This does three things:

Checks your environment (Node.js, pnpm, etc.)
Creates ~/.manasvi/ — where CLI config and logs are stored
Generates all required cryptographic secrets into .env.local — no manual editing needed

Expected output:

  Manasvi  init

  Checking prerequisites
  ✔ Node.js          v22.1.0
  ✔ pnpm             found
  ✔ tsx              found
  ✔ Manasvi project  /path/to/manasvi

  Generating secrets
  ✔ Generated 10 secrets → .env.local

  ✔ Manasvi initialized successfully

What is .env.local? It's a file that holds settings and secrets for your local Manasvi instance. Manasvi generates all the cryptographic values you need automatically — you don't need to create them yourself.

Step 4 — Onboard (2 min)

pnpm manasvi onboard

This walks you through choosing your model and connecting a channel. It's interactive — just follow the prompts.

Choose Ollama:

  Model Provider
  ? Which model provider do you want to use?
  ❯ Ollama (local)    Run models on your own machine — no API key needed
    OpenAI (cloud)    Use GPT models via OpenAI API key
    Claude (Anthropic cloud) Use Claude models via Anthropic API key
    Mock (testing)    Simulated responses — useful for testing the system

  ✔ Ollama is running at http://localhost:11434/v1
  ? Which Ollama model?  llama3.2
  ✔ Model: Ollama / llama3.2

Choose a channel (or skip for now):

You can connect Telegram now, or skip it and use the terminal chat interface first.

  Channels
  ? Connect a Telegram bot?  No

  Web UI & Docs
  ? Enable the documentation web UI?  Yes
  ✔ Docs UI will be available at http://localhost:3002

Step 5 — Start (1 min)

pnpm manasvi start

All nine services start in dependency order. You'll see them come up one by one:

  Starting services
  ✔ Policy
  ✔ Approval
  ✔ Memory
  ✔ Audit
  ✔ Execution Manager
  ✔ Node Manager
  ✔ Orchestrator
  ✔ Ingress
  ✔ API Gateway

  ✔ 9 service(s) started

  → pnpm manasvi status  check all service health
  → pnpm cli             chat with Manasvi in the terminal
  → pnpm manasvi stop    stop all services

Step 6 — Send your first message (2 min)

pnpm cli

This opens an interactive terminal chat. Type a message and press Enter:

Manasvi terminal  (session: session:abc123)
Type a message, or /help for commands.

You: What can you help me with?

Agent: I can help you with a range of tasks. I have access to tools like
       web search, file operations, and HTTP requests...

Try a few messages. Each one flows through the full pipeline: ingress → orchestrator → policy → (optionally) execution → audit.

tip

Type /session to see your current session ID, or /new to start a fresh conversation.

Step 7 — Check the status

In another terminal:

pnpm manasvi status

  Services
  API Gateway           :4100   ● healthy (12ms)
  Ingress Service       :4101   ● healthy (9ms)
  Orchestrator          :4102   ● healthy (14ms)
  Policy Service        :4103   ● healthy (8ms)
  Execution Manager     :4104   ● healthy (11ms)
  Memory Service        :4105   ● healthy (10ms)
  Node Manager          :4106   ● healthy (9ms)
  Audit Service         :4107   ● healthy (8ms)
  Approval Service      :4108   ● healthy (9ms)

  ✔ All 9 services healthy

  Configuration
  Model      Ollama / llama3.2
  Channels   none
  Docs UI    http://localhost:3002

You're up and running

You've just run a full governed AI agent pipeline locally:

Your message flowed through the ingress plane
The orchestrator resolved your session and asked the model what to do
The policy service evaluated whether any actions were allowed
The audit service recorded everything that happened

What tools does the agent have?

After starting up, your agent has access to the Starter Safe Set of tools:

Tool	What it does
Web search	Look things up on the web
HTTP fetch	Retrieve remote content
Local file read	Read workspace files

You can see all available tools and their governance status:

pnpm manasvi tools list
pnpm manasvi tools inspect tool.web-search
pnpm manasvi tools sets

Tools are governed: every invocation goes through policy evaluation, intent signing, and sandboxed execution. See Built-in tools overview for how it works.

What to do next

Explore the built-in tools — see what tools are available and how to configure them: → Built-in tools overview → Demo flows

Connect Telegram — send messages to your agent from your phone: → Connect Telegram

Connect Ollama with a different model — try Mistral, Qwen, or Llama 3.3: → Connect Ollama

Use OpenAI instead — switch to GPT-4o or GPT-4o-mini: → Configure a model

Use Claude instead — switch to Anthropic Claude models: → Connect Claude

Understand the system — learn what each part does and why: → Core concepts

Something went wrong? — run pnpm manasvi doctor first (add --fix for safe auto-repair): → Troubleshooting

Inspect logs — tail service output with pnpm manasvi logs <service> --follow

Check all connections — pnpm manasvi connections shows model, channel, and Google integration status in one view

What you'll need​

Step 1 — Get Ollama ready (5 min)​

Step 2 — Download Manasvi (1 min)​

Step 3 — Initialize (1 min)​

Step 4 — Onboard (2 min)​

Step 5 — Start (1 min)​

Step 6 — Send your first message (2 min)​

Step 7 — Check the status​

You're up and running​

What tools does the agent have?​

What to do next​