Viventium logo
Viventium
Docs
Troubleshooting

Troubleshooting

The fastest checks for install, startup, accounts, and local runtime issues on the current public path.

Start With These Commands

If something feels off, start here before digging deeper:

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

doctor is usually the best first move because it checks prerequisites and the local runtime state without making you guess.

Common Setup Problems

The installer does not finish cleanly

Check:

  • you are on the current public-ready local path
  • the installer was allowed to finish its prerequisite pass
  • you rerun bin/viventium doctor after install

If you are refreshing an existing setup after published fixes, run:

bin/viventium upgrade --restart

Viventium starts, but the local stack is unhealthy

Run:

bin/viventium doctor
bin/viventium stop
bin/viventium start

If the issue appeared after pulling new repo changes, upgrade first so the published component snapshots are current.

Connected Account Problems

If OpenAI or Anthropic is not showing up correctly after launch:

  1. Open Settings -> Connected Accounts
  2. Reconnect the provider you want to use
  3. Restart the local stack if the UI still looks stale

Important distinction:

  • Groq is used in the current public setup for lightweight background-agent wake-up checks
  • OpenAI or Anthropic is the main model path most people will actually use inside the product

Background Agent Problems

If background follow-through feels missing or noisy, diagnose in this order:

  1. Did activation happen? — Check if the activation detection (Groq) is running and the confidence threshold was met. A missing Groq key or unhealthy Groq connection will silently disable all background agents.
  2. Did execution happen? — The background agent needs a working model connection (OpenAI or Anthropic) and any tools it depends on (web search, workspace access).
  3. Did the follow-up merge back? — The result needs to make it back to the conversation via SSE. If the UI shows no follow-up, check whether the background cortex service is healthy.

That order matters because background-agent issues are almost always one layer failing, not the whole feature. Start from the outside in.

Config And Runtime Locations

The canonical local config lives at:

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

Generated runtime files live under:

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

That matters because the repo examples explain the supported shape, but your live machine state is compiled into App Support.

When To Take A Snapshot

If your local setup matters and you are about to make bigger changes, take a snapshot first:

bin/viventium snapshot

That gives you a safer recovery point before experimentation.

Voice Problems

If voice feels broken or laggy:

  • Verify LiveKit is running in the local stack (bin/viventium doctor checks this)
  • Whisper C++ and Chatterbox require adequate CPU/GPU — Apple Silicon handles this well, older Intel Macs may struggle
  • Check that no other application is holding the microphone exclusively

When To Ask For Help

Reach out when:

  • the installer repeatedly fails after doctor
  • Connected Accounts refuses to reconnect
  • background agents are clearly regressing
  • a documented command no longer matches the actual public path
  • voice latency is consistently high despite healthy stack

The best places to get help:

Keep Reading

Trust Model & Deployment