Installation

Get VibeOS running on your machine. Data and config live under ~/.vibeos.

Platform Support

For the full platform support matrix (OSes, distribution methods, and platform-gated features), see Platform Support.

Recommended: Desktop (macOS / Windows)

1. Download the latest build from vibeos.com.ru/download (Mac DMG or Windows Setup.exe).
2. macOS: open the DMG and run Install VibeOS (copies to Applications and clears Gatekeeper quarantine).
   Fallback: drag VibeOS to Applications, then right-click → Open → confirm.
   Windows: run the NSIS installer; if SmartScreen warns, choose More info → Run anyway.
3. Launch VibeOS. First start bootstraps the Python agent into ~/.vibeos/vibeos-agent and creates a virtualenv — no manual git clone required for Release builds.

Android: there is no APK yet — use Termux and scripts/install.sh (also linked from the download page).

Full macOS walkthrough: Installing VibeOS on macOS in the repo.

---

Command-line / from source

Bootstrap (recommended for developers)

git clone https://github.com/Linx72/VibeOS.git
cd vibeos
./scripts/bootstrap-vibeos.sh

That creates ~/.vibeos, installs deps into a venv, and links the vibeos / vibeos CLI entry points when available.

Optional: point the desktop app at your clone

./scripts/link-agent-home.sh

Symlinks ~/.vibeos/vibeos-agent → your checkout so the packaged app uses your local code.

After install

source ~/.zshrc   # or ~/.bashrc
vibeos            # or: vibeos  (legacy alias on many installs)
vibeos doctor     # health check

Configure provider and tools:

vibeos model          # Choose LLM provider and model
vibeos tools          # Enable / disable tools
vibeos gateway setup  # Messaging platforms
vibeos setup          # Full setup wizard

CLI name

Prefer vibeos. Many docs and scripts still show vibeos — both often work on the same install.

---

Install layout

Path	Role
~/.vibeos/	Config, .env (secrets), sessions, skills, logs
~/.vibeos/vibeos-agent/	Agent checkout or symlink (desktop bootstrap)
~/.vibeos/config.yaml	Non-secret settings
~/.vibeos/.env	API keys only

Legacy VibeOS homes (~/.vibeos) can be migrated into ~/.vibeos via the built-in home migrate path (vibeos doctor / migrate helpers).

---

Prerequisites (from-source)

• Git
• Python 3.11+ (bootstrap/uv may install a managed interpreter)
• Node.js (desktop UI, browser automation, WhatsApp bridge — as needed)
• On Linux for Playwright/Chromium: system libs (libnss3, etc.) or run admin playwright install-deps once

Nix users

Nix is best-effort only. See Nix & NixOS Setup.

---

Manual / developer installation

For contributing or running a specific branch, see Development Setup in the Contributing guide.

---

Troubleshooting

Problem	Solution
vibeos: command not found / vibeos: command not found	Reload the shell; ensure ~/.local/bin (or your venv bin) is on PATH
API key not set	Run vibeos model or set keys in ~/.vibeos/.env
Missing config after update	vibeos config check then vibeos config migrate
Desktop won't open (macOS)	Run Install VibeOS from the DMG, or right-click → Open, or xattr -cr /Applications/VibeOS.app

For diagnostics: vibeos doctor — it reports what's missing and how to fix it.

Updates

See Updating & Uninstalling. Desktop users can also install a newer build from vibeos.com.ru/download.