Getting Started with OpenViber

OpenViber is a platform for running AI tasks on your machine. There are two ways to set it up:

• Standalone mode: local CLI/daemon only, no web control plane required.
• Connected mode: your local Viber is registered to a Gateway and controlled from the Viber Board (web UI).

Use this guide if you want explicit onboarding steps for both modes and a clear picture of how Viber ↔ Gateway ↔ Viber Board are wired together.

Option A: Connect to OpenViber Web (Recommended)

This connects your local Viber to the web dashboard where you can manage config, send tasks, and monitor your Viber remotely.

Step 1: Create a Viber on the Web

1. Log in to OpenViber Web (or your deployed URL)
2. Go to Vibers → Click “Add Viber”
3. Give your Viber a name
4. Copy the generated command

Optional: Create a task from an intent

After the Viber is online, open Tasks → New Task and choose an intent template (for example, Build a Feature or Code Review).

The task launch flow is:

1. Select an active Viber
2. Select an intent template (or paste your own goal)
3. OpenViber infers required skills from template metadata, skills: blocks, and keywords
4. If the selected Viber is missing required skills, OpenViber starts guided provisioning before launch
5. After prerequisites are ready, the task launches automatically with the selected intent body

Supported proactive skill provisioning currently covers:

• cursor-agent
• codex-cli
• gemini-cli
• github
• gmail
• railway
• tmux (terminal backing skill)

You can manage templates in Settings → Intents.

Step 2: Run the Onboard Command

Paste the command in your terminal:

npx openviber onboard --token <token>

This will:

• Install/update OpenViber
• Create ~/.openviber/ configuration directory
• Connect your machine to the web dashboard
• Save connection config for future use

Note: The token expires in 15 minutes. If it expires, generate a new one on the web.

Step 3: Set Your API Key

export OPENROUTER_API_KEY="sk-or-v1-xxx"

Get an API key at: openrouter.ai/keys

Step 4: Start Your Viber

npx openviber start

That’s it! Your Viber will automatically connect to OpenViber Web. No extra flags needed — it reads your saved config.

Option B: Standalone Setup (Local Only)

If you just want to run a Viber locally without the web dashboard:

npx openviber onboard

Then:

export OPENROUTER_API_KEY="sk-or-v1-xxx"
npx openviber start

You can connect to OpenViber Web later:

npx openviber onboard --token <token-from-web>

Wiring Overview: Standalone vs Gateway + Board

Standalone (Viber only)

You (terminal)
   │
   ▼
OpenViber CLI/Daemon on your machine
   │
   └── Uses local ~/.openviber state + your model API key

In this mode, there is no remote registration handshake.

Connected (Viber + Gateway + Board)

Viber Board (Web UI :6006)
   │   HTTPS / WS
   ▼
Viber Gateway (:6007)
   │   WS
   ▼
Your local OpenViber Daemon (Viber)

Connected mode uses an onboarding token to bind your local Viber to the gateway project/workspace so the board can dispatch tasks and observe status.

Component Responsibilities

Onboarding Checklist by Mode

Standalone checklist

1. Run npx openviber onboard.
2. Set OPENROUTER_API_KEY (or your configured provider key).
3. Start with npx openviber start.
4. Validate locally with npx openviber status or npx openviber chat.

Connected checklist (Gateway + Board)

1. Open Viber Board and create a Viber to obtain a token.
2. On the target machine, run npx openviber onboard --token <token> within 15 minutes.
3. Start the daemon (npx openviber start).
4. Verify the Viber appears active/selectable in Vibers and New Task flows.
5. Launch a test task from the board and confirm round-trip events.

Current Gaps to Watch While Wiring

When integrating Viber + Gateway + Board, these are common missing pieces to identify early:

• Connection diagnostics are still mostly manual: users often fall back to status, logs, and page refreshes to understand handshake failures.
• Token lifecycle UX can be improved: expired/invalid token feedback is functional but could be more guided across CLI and board.
• Post-onboarding verification is implicit: there is no single built-in onboarding doctor flow that checks key, connectivity, and Viber readiness end-to-end.
• Mode visibility could be clearer: users may not immediately know whether they are running purely standalone or currently linked to a gateway workspace.

If you are setting up team onboarding, treat the checklist above as a baseline and document your environment-specific validation steps (auth provider, deployment URL, proxy, and firewall rules).

File Structure

After onboarding, your ~/.openviber/ directory looks like:

~/.openviber/
├── config.yaml          # Connection config (auto-generated)
├── viber-id             # Unique machine identifier
├── user.md              # Your context (shared across tasks)
├── vibers/              # Task configurations
│   ├── default.yaml     # Default task configuration
│   └── default/
│       ├── soul.md      # Task personality
│       └── memory.md    # Long-term notes
└── skills/              # Custom skills

Commands Reference

Troubleshooting

Token expired? Create a new Viber on the web and run npx openviber onboard --token again.

Can’t connect? Make sure OpenViber Web is running. By default: http://localhost:6006

Intent launch says a skill is missing? Keep the target Viber selected and use the guided setup dialog to provision prerequisites, then retry launch.

Viber not selectable in New Task? Only active (connected) Vibers can receive launches. Start your local daemon with npx openviber start and refresh the page.

Need to switch modes? You can always re-run npx openviber onboard --token <token> to switch from standalone to connected mode.