Docs & Setup

1. Requirements

• Node.js ≥ 18.18.0 — the CLI is an npm package.
• macOS, Linux or Windows.
• A model to talk to. Either a cloud API key (Groq, Google Gemini, NVIDIA NIM, OpenRouter, OpenAI, Anthropic, Mistral, …) or a local model via Ollama — local is a first-class path, not a fallback, and costs nothing per token.

No account with us is required, and nothing is sent anywhere except the model providers you configure yourself. There is no telemetry and no cloud dashboard — the local dashboard is the source of truth.

2. Install

Install globally from the public npm registry:

Then confirm the binary answers:

agent-nuvira, buff and nuvira are the same program. This page uses nuvira because it is the shortest to type; every example works with any of the three.

3. Connect a provider

Pick one provider to start — you can add more later, and the router will use all of them. A free key is enough to try everything.

Environment variable (fastest):

Or store it in config so it survives the shell session — use the OS keychain instead of a plaintext file:

Priority, highest first: CLI flags (--provider, --model) → environment variables → config file (~/.nuvira/) → defaults.

4. First run

nuvira doctor is the fastest way to know whether your setup is sound. It prints a full health report — config directory, secret vault tier, memory store, plugin directories, and a probe of every provider you hold a key for.

Expect the first run to be slow. Model discovery walks every provider you have a key for; later runs use the cache. If it reports nothing usable, nuvira doctor --verbose names exactly what it found.

5. The dashboard and a channel

The CLI is one surface, not the whole product. The dashboard is the visual one, and the gateway puts the same agent inside a chat app. Both take a few minutes.

Start it, and log in

It serves http://127.0.0.1:3030 and opens a browser. --port moves it, --host 0.0.0.0 exposes it on your network, --no-open stays quiet, --force restarts a stale instance, and nuvira dashboard stop shuts it down from any terminal.

Your first login is admin / admin. That pair is published, so the account it creates can do exactly one thing: change the password. Every write route — provider config, API keys, users, shutdown — is refused until you set a real one of at least 8 characters. That is deliberate: the default is a doorway, never a resting state. Sessions last 8 hours and are dropped when the server restarts.

Add the people who may use it

An admin adds users from the Admin page, each with an explicit role. You cannot remove your own user, and the last admin cannot be removed, so the UI cannot leave an installation with nobody able to administer it. An unknown user resolves to viewer — the failure mode is deny, not allow.

Open a project in the console

The console is directory-scoped, like the CLI. The picker offers the dashboard's own working directory plus every path attached to the session, with a folder browser behind it. Choose one and the chat, the file tools, the diffs and the run all operate on that directory — the same as starting nuvira chat inside it.

A messaging channel in two minutes

The wizard asks for exactly the variables the platform needs and then validates the credential against the live service before telling you it worked. Telegram needs a bot from @BotFather; send your bot a message afterwards to learn your own chat id for the allow-list.

WhatsApp uses your own number through a pairing QR — no Meta Business account and no paid API:

Platform tokens are stored in ~/.nuvira/.env, written by both the wizard and the dashboard's Channels tab. WhatsApp is the exception: a paired session on disk, not a token.

Who may trigger the agent

An unknown sender is neither obeyed nor necessarily dropped — nuvira gateway contact list shows them pending, and approve or reject decides.

Adding a contact for send-by-name does not grant trigger access. They are separate lists on purpose: who may drive the agent and who may be spoken to as you are two different permissions.

Keep it up

nuvira gateway start --supervise restarts the adapters after a crash; surviving a reboot needs a login unit — the manual has the recipe for macOS, Linux and Windows. One trap: nuvira dashboard already starts a gateway beside itself, so don't give the same platform two owners.

6. Everyday commands

The same pipeline, tools and router sit behind every surface, so you can start in the terminal and pick up the same thread in the dashboard or from a messaging channel.

There are 289 command entries across 48 groups. The full command surface is generated from the live CLI, so it cannot describe a command that does not exist.

7. Recipes

nuvira workflow run bug-hunt "login fails when the email has a plus sign"
nuvira ci check "the login plus-sign bug is fixed"

nuvira skill run security-audit --params "focus=secrets,ssrf"
nuvira security scan "$(git diff --cached)"
nuvira sbom > sbom.json
nuvira code-map src > map.txt

nuvira chat "clone vercel/next.js and summarise how routing is implemented"

- run: nuvira ci check "no TypeScript errors introduced"
- run: nuvira security scan "$(git log -1 --pretty=%B)"

nuvira stats
nuvira retrieval stats

8. Troubleshooting

9. Go deeper

The complete documentation is public — read it in the browser on GitHub, no account needed.