Vilvona AI Documentation

Vilvona AI is a self-hosted personal AI assistant built on OpenClaw (MIT). It connects to WhatsApp, Telegram, Slack, Gmail, Discord, Notion, GitHub, and 100+ more apps from one clean web interface. Everything runs locally — no cloud accounts, no data sent to third parties.

Vilvona adds three things on top of OpenClaw: Claude Fable 5 as the default AI model, native Tamil and Hindi UI, and an enhanced Mobile PWA experience.

Claude Fable 5

Default model — 1M context, computer use, best-in-class reasoning from Anthropic.

21 Languages

Tamil and Hindi built-in. The first AI assistant to natively support India's languages.

Mobile PWA

Install from your browser on iOS or Android. No app store required.

Self-Hosted

Runs entirely on your machine. No accounts, no telemetry, no cloud lock-in.

BYOK

Use your own Anthropic API key. Pay per token directly. Vilvona never touches your billing.

100+ Integrations

WhatsApp, Telegram, Slack, Discord, Gmail, Notion, GitHub and many more.

Quick Start

Run Vilvona AI in under 60 seconds. You only need Node.js 22+ and an Anthropic API key.

1. Get an API key

Sign up at console.anthropic.com and create an API key. You pay per token — there is no monthly fee.

2. Run Vilvona AI

bash

        export ANTHROPIC_API_KEY=sk-ant-...

        npx vilvona

3. Open the interface

Visit http://localhost:4000 in your browser. Vilvona AI is ready.

First run: Vilvona downloads the OpenClaw runtime (~97 MB) to ~/.vilvona/runtime/ automatically. This only happens once. Subsequent starts are instant.

4. (Optional) Install on your phone

Find your machine's local IP address (ip addr on Linux, ifconfig on Mac). Then open http://<your-ip>:4000 on your phone and add to home screen.

How it works

When you run npx vilvona, the Vilvona launcher (openclaw.mjs) does the following:

Checks your Node.js version is 22.19+ (shows a clear fix if not)
Prints the Vilvona AI banner
Downloads the OpenClaw runtime to ~/.vilvona/runtime/ (first run only)
Sets OPENCLAW_DEFAULT_MODEL=anthropic/claude-fable-5
Launches the OpenClaw runtime, which starts the web UI at port 4000

architecture

        npx vilvona

          └── openclaw.mjs (Vilvona launcher)

                ├── Node 22+ check

                ├── Print Vilvona banner

                ├── Download openclaw → ~/.vilvona/runtime/ (once)

                ├── Set OPENCLAW_DEFAULT_MODEL=claude-fable-5

                └── Launch runtime → http://localhost:4000

The OpenClaw runtime is a self-contained ~97 MB bundle that includes the entire web UI, API server, and all integration adapters. Vilvona AI sits on top of it as a thin launcher that sets your preferences and adds Vilvona-specific features.

Installation

Vilvona AI works on Mac, Windows, and Linux. Node.js 22.19+ is required.

Recommended: Use npx vilvona — no install needed, always runs the latest version.

npx — no install needed

The simplest way. No global install, always up-to-date.

bash

npx vilvona

yarn

Run without installing, or install globally.

bash

        # Enable yarn first (one-time)

        corepack enable

        # Run without install

        yarn dlx vilvona

        # Or install globally

        yarn global add vilvona

        vilvona

pnpm

Run without installing, or install globally.

bash

        # Run without install

        pnpm dlx vilvona

        # Or install globally

        pnpm add -g vilvona

        vilvona

Note: If pnpm dlx fails on a brand-new release with a "minimumReleaseAge" error, either use npx vilvona or run: pnpm config set minimumReleaseAge 0

Docker

bash

        # Quick start

        docker run \

          -e ANTHROPIC_API_KEY=sk-ant-... \

          -p 4000:4000 \

          ghcr.io/vignesh2027/vilvona-ai

        # With persistent data

        docker run \

          -e ANTHROPIC_API_KEY=sk-ant-... \

          -v ~/.vilvona:/root/.openclaw \

          -p 4000:4000 \

          ghcr.io/vignesh2027/vilvona-ai

Windows (PowerShell)

powershell

        $env:ANTHROPIC_API_KEY = "sk-ant-..."

        npx vilvona

From Source

Clone the repository and run directly.

bash

        git clone https://github.com/vignesh2027/Vilvona-AI.git

        cd Vilvona-AI

        # Check Node version

        node --version  # Must be 22+

        # Run

        node openclaw.mjs

Configuration

Environment variables

Variable	Description	Default
`ANTHROPIC_API_KEY`	Your Anthropic API key. Get one at console.anthropic.com. Required.	—
`VILVONA_DEFAULT_MODEL`	Model alias. Options: `fable`, `opus`, `sonnet`	`fable`
`VILVONA_PRO_KEY`	Pro license key. Format: `VLVN-XXXX-XXXX-XXXX-XXXX`	—
`OPENCLAW_PORT`	Port for the web UI to listen on	`4000`

Config file

Vilvona AI stores its configuration at ~/.openclaw/config.json.

~/.openclaw/config.json

        {

          "defaults": {

            "model": "anthropic/claude-fable-5"

          },

          "ui": {

            "locale": "ta"  // Tamil — use "hi" for Hindi

          }

        }

AI Models

Alias	Model ID	Best For
`fable` Default	`anthropic/claude-fable-5`	Most capable. Best reasoning, 1M context, computer use.
`opus`	`anthropic/claude-opus-4-8`	Balanced. Strong reasoning with faster output.
`sonnet`	`anthropic/claude-sonnet-4-6`	Fast and affordable. Good for everyday tasks.

Languages

Vilvona AI is the first AI assistant with built-in Tamil and Hindi UI. The language is set automatically based on your browser settings, or you can set it manually.

To set the language manually, add to your config:

json

        { "ui": { "locale": "ta" } }  // Tamil

        { "ui": { "locale": "hi" } }  // Hindi

Language	Native Script	Code	Notes
TamilIndia	தமிழ்	`ta`	Full UI — added by Vilvona
HindiIndia	हिन्दఈ	`hi`	Full UI — added by Vilvona
English	English	`en`	Default
Chinese	中文	`zh-CN`	Supported
Japanese	日本語	`ja-JP`	Supported
Korean	한국어	`ko`	Supported
Arabic	العربية	`ar`	Supported
French	Français	`fr`	Supported
German	Deutsch	`de`	Supported
Spanish	Español	`es`	Supported
+ 11 more languages			21 total

Mobile PWA

Vilvona AI works as a full mobile app installed from your browser. No App Store, no Play Store, no approval process.

Install on iPhone (Safari)

Open http://<your-machine-ip>:4000 in Safari
Tap the Share button (square with arrow)
Tap Add to Home Screen
Vilvona AI is now on your home screen as a native-looking app

Install on Android (Chrome)

Open http://<your-machine-ip>:4000 in Chrome
Tap the three-dot menu in the top right
Tap Add to Home screen or Install app
Done

Find your machine's IP address

bash

        # Mac

        ipconfig getifaddr en0

        # Linux

        hostname -I

        # Windows

        ipconfig # look for IPv4 Address

Tip: Your phone and your computer must be on the same Wi-Fi network.

Integrations

Vilvona AI inherits all 100+ integrations from OpenClaw. Connect your apps from the Settings panel inside the UI.

Category	Apps
Messaging	WhatsApp, Telegram, iMessage (Mac), Signal, Discord
Work	Slack, Gmail, Notion, GitHub, Linear, Jira, Confluence
Social	Instagram DM, Twitter/X
Productivity	Google Calendar, Google Drive, Dropbox, OneDrive
Developer	GitHub, GitLab, Webhooks, Custom MCP servers
Communication	Microsoft Teams, Google Meet

Pro Tier

Vilvona AI Pro is a one-time purchase (‍₹4,100, ~$49 USD) that unlocks enterprise and team features. No subscription, no monthly fee, lifetime access.

Buy at: vignesh2027.mojo.page/vilvona-ai-pro

Feature	Free	Pro
Claude Fable 5	Yes	Yes
All integrations	Yes	Yes
Tamil & Hindi UI	Yes	Yes
Mobile PWA	Yes	Yes
Enterprise audit logs	—	Yes
Team config sync	—	Yes
Priority Fable 5 routing	—	Yes
Custom AI personas (unlimited)	—	Yes
Webhook & Zapier integrations	—	Yes
White-label branding	—	Yes

Activate your Pro key

After purchase, you will receive a key in the format VLVN-XXXX-XXXX-XXXX-XXXX.

bash

        export VILVONA_PRO_KEY=VLVN-XXXX-XXXX-XXXX-XXXX

        vilvona

To make the key permanent, add export VILVONA_PRO_KEY=... to your ~/.zshrc or ~/.bashrc.

Troubleshooting

Node.js version error

Vilvona AI requires Node.js 22.19 or newer.

bash — fix with nvm

        nvm install 22

        nvm use 22

        nvm alias default 22

        npx vilvona

pnpm dlx fails with release age error

pnpm has a supply-chain security feature that blocks packages younger than a configured minimum age.

bash — fix

        pnpm config set minimumReleaseAge 0

        pnpm dlx vilvona

Or simply use npx vilvona instead.

yarn dlx fails

Yarn v2+ requires Corepack to be enabled first.

bash — fix

        corepack enable

        yarn dlx vilvona

Port 4000 already in use

bash

        OPENCLAW_PORT=4001 npx vilvona

Runtime download fails

If the first-run download fails due to network issues, try again. The download is ~97 MB. If your company blocks npm, use the Docker image instead.

Clearing the runtime cache

bash

        # Delete cached runtime — will re-download on next run

        rm -rf ~/.vilvona/runtime

FAQ

Is Vilvona AI free?

Yes. The core product is MIT licensed and free to use. You pay Anthropic directly for API tokens. There is also a paid Pro tier for enterprise features.

Does Vilvona AI send my data anywhere?

No. Vilvona AI runs entirely on your machine. Your conversations go directly from your browser to Anthropic's API. Vilvona never stores or sees your messages.

How is Vilvona AI different from OpenClaw?

Vilvona AI is a fork of OpenClaw (MIT license) with three additions: Claude Fable 5 as the default model, native Tamil and Hindi UI, and an enhanced mobile PWA. It is packaged on npm so you can run it with npx vilvona without building from source.

Can I use models other than Claude?

Yes. OpenClaw supports many providers including OpenAI, Google Gemini, Mistral, and others. Set your preferred model in the UI settings or via environment variables.

Will it work on Windows?

Yes. Use PowerShell to set environment variables and run npx vilvona. Node.js 22+ must be installed.

How do I update Vilvona AI?

bash

        # npx always runs the latest version automatically

        npx vilvona@latest

        # If installed globally

        npm update -g vilvona

Where is my data stored?

Conversations, settings, and credentials are stored locally at ~/.openclaw/. The OpenClaw runtime cache is at ~/.vilvona/runtime/.

Changelog

v1.0.4 2026-06-12

Fix: --version now shows the actual installed version instead of hardcoded 1.0.0
Fix: npm homepage now points to the documentation site
Docs: comprehensive documentation with sidebar navigation, quickstart, troubleshooting, FAQ
README: professional full documentation

v1.0.3 2026-06-12

Added yarn (yarn dlx vilvona) and pnpm (pnpm dlx vilvona) support
CI: GitHub Actions validate job green with 12/12 checks
NPM_TOKEN connected to GitHub Actions for automatic releases
pnpm minimumReleaseAge set to 0 to fix supply-chain block

v1.0.2 2026-06-12

Vilvona AI ASCII banner printed on startup
Windows signal handling (SIGTERM, SIGINT, SIGBREAK)
Branch protection on main
GitHub topics and FUNDING.yml

v1.0.1 2026-06-12

Tamil (ta) and Hindi (hi) locale support
Pro tier license key validation (VLVN- format)
Instamojo payment page for Pro licenses
Mobile PWA enhanced manifest

v1.0.0 2026-06-11

Initial release — Vilvona AI fork of OpenClaw
Claude Fable 5 as default model
npm publish: npx vilvona
GitHub Pages documentation site