Install & Setup

Before You Start

The current public-ready path is the local install path from the repo.

Have these ready:

• a Groq API key for lightweight background-agent wake-up checks
• either an existing OpenAI or Anthropic account for the simplest connected-account path, or API keys for the provider and model you want to use
• the public GitHub repo

1. Clone The Repo And Run The Installer

git clone https://github.com/ProjectViventium/viventium.git
cd viventium
./install.sh

The installer writes the canonical local config to:

~/Library/Application Support/Viventium/config.yaml

2. Validate And Start The Local Stack

bin/viventium doctor
bin/viventium start

Useful follow-up commands:

bin/viventium upgrade --restart
bin/viventium stop
bin/viventium snapshot

3. Connect Your Main AI Account

After launch, open:

Settings -> Connected Accounts

Then either connect your existing OpenAI or Anthropic account for the simplest subscription-backed path, or configure API keys for another supported provider and model.

That connected-account path is the easiest way for most people to get going, but it is not the only option.

What Groq Is Doing In The Setup

Groq is not the main AI you talk to — it is used for the lightweight activation checks that decide whether background agents should wake up.

When you send a message, a fast Groq inference evaluates whether the conversation warrants deeper background work (research, fact-checking, red-teaming, etc.). This keeps the routing layer fast and cheap without forcing every message through a heavier model.

Your actual conversations and deep thinking can go through the OpenAI or Anthropic account you connect, or through another supported provider and model if you configure API keys for it.

Headless Configuration

For automated or scripted setups, the installer supports headless mode:

./install.sh --headless --config-input path/to/answers.yaml

This writes the same canonical config without interactive prompts. Useful for CI, fleet deployment, or reproducible setups.

What Happens After Setup

Once the local stack is healthy and your account is connected, you can start using Viventium for real work across:

• chat
• voice
• messaging surfaces like Telegram
• connected workspaces
• scheduled briefings and reminders
• project-based follow-through

First Use

After you have connected your account and confirmed Viventium is working, one of the best first moves is to transfer the context you already built in ChatGPT or another AI you used before.

Go to that older AI and paste a prompt like this:

Generate a fully detailed knowledge transfer regarding everything you know about me and my life, preferences, likes, dislikes, plans, goals, memories, and ongoing context.

Then paste the result into Viventium.

That gives Viventium a much better starting point right away instead of making you rebuild all of your context from scratch.

Good First Tasks

Start with something real instead of a demo prompt.

Examples:

• "Help me think through this decision and pressure-test it."
• "Pull together what matters from my inbox and calendar."
• "Turn these messy notes into a cleaner brief."
• "Check this site, gather the important changes, and summarize the tradeoffs."

Where Local Runtime Files Live

Generated runtime files live under:

~/Library/Application Support/Viventium/runtime/
~/Library/Application Support/Viventium/state/runtime/

That matters when you want to understand the difference between repo examples and your live local configuration.

If Something Breaks

Start with:

bin/viventium doctor

Then use Troubleshooting for the fast recovery path.

Keep Reading

• Trust Model & Deployment — Understand what runs where and why
• Architecture Overview — See the full system you just installed
• Background Agents — How the wake-up and follow-through model works
• Voice, Chat & Messaging — Where the same continuity shows up across surfaces
• Troubleshooting — Recovery steps when things break