Install and onboarding

Two ways to run VibeAround: the desktop app (recommended — GUI management plus the embedded server) or the npm CLI (headless server for terminal-first setups and remote machines). Both produce the same daemon with the same data directory, so you can switch later without losing anything.

Option 1: desktop app

Download the package for your platform from the GitHub releases page:

macOS Intel is currently source-build only — see Build from source.

Install and launch. The app lives in the tray/menu bar; closing the window does not stop the daemon.

First-run onboarding

The desktop app walks you through setup on first launch:

1. Toolchain check. VibeAround needs Node.js for agent ACP adapters and channel plugins. Onboarding detects your system toolchain, or installs a managed one if you prefer not to touch the system (toolchain setting: system or managed).
2. Agent detection. Installed agent CLIs (Claude Code, Codex, Gemini CLI, …) are detected on PATH; you choose which to enable. Agents you enable get VibeAround's MCP endpoint and skills injected into their global config so hosted sessions have the integration tools available.
3. Model profiles (optional). Add a provider credential now, or skip and use agents with their own vendor logins (the direct profile).
4. Channels (optional). Install and configure IM channel plugins. Each channel needs platform-side setup (bot tokens etc.) covered in Connect channels; you can do this any time later.

After onboarding, the dashboard opens in your browser, already authenticated. You are ready for the Quick tour.

Option 2: npm CLI

npm i -g @vibearound/cli

This installs the va and vibearound commands, the native server binaries, the va-launch native launcher, the TUI, and the pre-built web dashboard.

Start the server:

va serve

The daemon binds 127.0.0.1:12358, writes its auth token to ~/.vibearound/auth.json, and serves the dashboard at http://127.0.0.1:12358/va/ (open it with the token — va status shows the URL). Configuration is ~/.vibearound/settings.json, created with defaults on first run; there is no GUI onboarding in this mode: configure channels and profiles through the web dashboard, or by editing settings.json directly (see Reference). Dedicated CLI commands for configuration are planned. With the desktop app, none of this file editing applies — configuration lives in the UI.

Useful first commands:

va status      # runtime summary: channels, tunnels, agents, sessions
va doctor      # diagnose endpoint, auth, and server health
va agents      # list enabled agents
vibearound tui # terminal UI

The data directory

Everything VibeAround persists lives in ~/.vibearound/ (override with VIBEAROUND_DATA_DIR):

~/.vibearound/
├── settings.json         # main configuration
├── auth.json             # dashboard auth token (regenerated each start)
├── agents.json           # detected agent executables
├── plugins/              # installed channel plugins
├── workspaces/           # default root for created workspaces
├── launch/profiles/      # saved va-launch profiles
└── *.jsonl               # workspace/thread/attachment event logs

Uninstalling the app or package never deletes this directory; remove it manually for a clean slate.

Upgrading

• Desktop: install the new package over the old one; data directory is untouched.
• npm: npm i -g @vibearound/cli@latest.
• Check release notes for breaking changes before major upgrades — settings migrations run automatically on daemon start, but channel plugins may need va channel sync afterwards.

Source anchors: src/npm/cli/ (package contents), src/core/src/config.rs (data_dir, DEFAULT_PORT, settings bootstrap), src/desktop/src/onboarding/ (onboarding steps), src/core/src/toolchain.rs (system/managed), src/cli/src/args.rs (va commands). Last verified: v0.7.11