Skip to main content

Installation Guide

Viben: Agent Swarm x Code Evolution​

Viben is an AI-driven code iterative optimization and agent swarm orchestration platform. Core capabilities include:

  • FileEvo (File-based Self-Evolution) - Feedback-based code iterative optimization system
  • Agent Swarm - Multi-agent swarm orchestration and collaboration
  • Task System (XState) - State machine-based task workflow management
  • Idea Generation - AI-assisted idea generation and knowledge exploration

Product Forms​

Viben offers multiple product forms. You can choose to install based on your needs:

ProductInstallation MethodUse Cases
Desktop AppDownload installerAgent Swarm orchestration, FileEvo code optimization, task management
CLI Toolnpm/npxCommand line automation, task state machine, Queue system
MCP Serverpip/uvAI assistant integration for academic search, knowledge acquisition

The desktop app is the most intuitive way to experience Agent Swarm x Code Evolution, providing a complete graphical interface:

  • Agent Swarm - Visual orchestration and management of agent swarms
  • FileEvo - Visual feedback interface for code iterative optimization
  • Task System - XState-based task state machine management
  • Idea Generation - AI-assisted knowledge exploration and idea generation

Download​

Latest Version

Download the latest version from GitHub Releases:

PlatformDownload FormatNotes
macOS.dmg (Universal)Supports Intel and Apple Silicon
Windows.msi or .exe64-bit Windows 10/11
Linux.AppImage or .deb64-bit Linux

macOS Installation​

  1. Download the .dmg file
  2. Double-click to open the disk image
  3. Drag Viben to the Applications folder
  4. On first launch, right-click and select "Open" (to bypass Gatekeeper)

:::note macOS Security Note If you see "Viben is damaged and can't be opened", run in terminal:

sudo /usr/bin/xattr -cr /Applications/Viben.app

:::

Windows Installation​

  1. Download the .msi or .exe installer
  2. Run the installer
  3. Follow the installation wizard to complete installation
  4. Launch Viben from the Start menu

Linux Installation​

AppImage (Portable):

chmod +x Viben_*.AppImage
./Viben_*.AppImage

Debian/Ubuntu:

sudo dpkg -i Viben_*_amd64.deb
sudo apt-get install -f  # Fix dependencies

CLI Tool​

Viben CLI is the command line entry point for Agent Swarm x Code Evolution, suitable for automation and script integration:

  • Task System - viben task manages task state machine workflows
  • Queue System - viben queue background command execution queue
  • Agent Management - Command line management of agent swarms

No installation needed, run directly:

npx viben

Global Installation​

npm install -g viben

After installation, you can use the viben command directly:

viben --help

Verify Installation​

viben version

Main Commands​

viben <command> [options]

Core:
  init          Initialize a Viben workspace with AI-assisted development workflow
  config        Manage Viben configuration (git-style get/set)
  gateway       Manage the Viben Gateway (start/stop/status)
  service       Manage background services

Agent:
  agent         Manage AI agents (create, update, list, chat, memory, sessions)
  executor      Manage AI coding agent executors (list, show, chat)

Task:
  task          Manage development tasks (state machine workflows)
  queue         Manage background command execution queue
  swarm         Manage multi-agent pipelines using git worktrees

AI:
  idea          AI-driven idea generation and management
  evo           Evo - File-based Self-Evolution for code optimization
  reward        Reward type management for Evo

Tools:
  mcp           MCP (Model Context Protocol) utilities
  skill         Manage skills (install, search, enable/disable)
  channel       Manage notification channels
  cron          Manage scheduled cron jobs

Workspace:
  workspace     Workspace operations (list, current)
  session       Session recording management
  context       Get current development context
  user          Manage user identity
  page          Manage workspace pages

Config:
  provider      Manage AI providers
  model         Manage AI models (aliases, fallback, config)
  update        Update Viben CLI or workspace components

Telemetry:
  telemetry     Manage telemetry traces and logs

Auth:
  login         Log in to Viben with an API token
  logout        Log out and remove saved token
  whoami        Show current logged-in user

MCP Server​

The MCP server provides knowledge acquisition capabilities for Agent Swarm, supporting academic paper search and multi-source data access. It is an important knowledge source for Idea Generation and FileEvo.

Quick Installation​

pip install browse-mcp

Using uv​

If you use uv as your package manager:

uv pip install browse-mcp

Shell Script Installation​

Quick installation on macOS or Linux:

curl -fsSL https://github.com/LinXueyuanStdio/viben/releases/latest/download/install.sh | bash

Verify Installation​

browse-mcp --help

Example output:

Usage: browse-mcp [OPTIONS] COMMAND [ARGS]...

  Run the Browse MCP server.

Options:
  --host TEXT           Bind host (SSE/HTTP only).  [default: 127.0.0.1]
  --port INTEGER        Bind port (SSE/HTTP only).  [default: 8000]
  --debug / --no-debug  Enable debug logging.  [default: no-debug]
  -t, --transport TEXT  Transport method: stdio, sse, streamable-http, http
  --help                Show this message and exit.

Start Server​

browse-mcp
tip

The server runs in stdio mode by default, which is what MCP clients like Claude Desktop expect. You don't need to keep the terminal open; the MCP client will automatically start the server.

Install from Source (Developers)​

Clone Repository​

git clone https://github.com/LinXueyuanStdio/viben.git
cd viben

Install Dependencies​

pnpm install

Build Project​

pnpm build

Start Development Services​

Desktop App:

pnpm dev:desktop

Gateway Service:

pnpm gateway:build

System Requirements​

Desktop App​

PlatformMinimum Requirements
macOSmacOS 10.15 (Catalina) or higher
WindowsWindows 10 (64-bit) or higher
LinuxUbuntu 20.04 or equivalent (64-bit)

Recommended Configuration:

  • 4 GB RAM
  • 100 MB disk space
  • Network connection

CLI Tool​

  • Node.js 18+ or 20+
  • npm or pnpm

MCP Server​

  • Python 3.10 or higher
  • pip or uv

Next Steps​