> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> How to install and set up the VibeKit CLI on your system

## Prerequisites

Before installing the VibeKit CLI, ensure you have:

* **Node.js** version 18.0.0 or higher
* **npm** or **yarn** package manager
* **Docker** installed and running (optional, for maximum security)
* **Claude Code CLI** or **Gemini CLI** for the agents you want to use

## Installation Methods

### Global Installation (Recommended)

Installing globally makes the `vibekit` command available system-wide:

<CodeGroup>
  ```bash npm theme={"dark"}
  npm install -g vibekit
  ```

  ```bash yarn theme={"dark"}
  yarn global add vibekit
  ```

  ```bash pnpm theme={"dark"}
  pnpm add -g vibekit
  ```
</CodeGroup>

### Project Installation

For project-specific installations:

<CodeGroup>
  ```bash npm theme={"dark"}
  npm install --save-dev vibekit
  ```

  ```bash yarn theme={"dark"}
  yarn add --dev vibekit
  ```

  ```bash pnpm theme={"dark"}
  pnpm add -D vibekit
  ```
</CodeGroup>

### Using npx (No Installation)

Run commands without installing:

```bash theme={"dark"}
npx vibekit claude "Generate a REST API"
npx vibekit dashboard
```

## Verify Installation

After installation, verify that the CLI is working:

```bash theme={"dark"}
# Check version
vibekit --version

# View help
vibekit --help
```

## Post-Installation Setup

### 1. Install Required Agents

Install the coding agents you want to use:

```bash theme={"dark"}
# Install Claude Code CLI
npm install -g @anthropic/claude-code

# Install Gemini CLI (if available)
# Follow Gemini CLI installation instructions
```

### 2. Configure Environment Variables

Set up your API keys:

```bash theme={"dark"}
# For Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# For Gemini
export GOOGLE_API_KEY="..."

# For proxy configuration (optional)
export HTTP_PROXY="http://proxy.example.com:8080"
```

Or add them to your shell profile (`~/.bashrc`, `~/.zshrc`):

```bash theme={"dark"}
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc
```

### 3. Configure Settings (Optional)

Run the settings interface to configure VibeKit:

```bash theme={"dark"}
vibekit
```

This allows you to:

* Enable/disable Docker sandbox
* Configure proxy server settings
* Enable/disable analytics
* Set up global aliases

### 4. Docker Setup (Optional)

For maximum security, ensure Docker is running:

```bash theme={"dark"}
# Check Docker status
docker info

# Start Docker daemon if needed
# On macOS: Open Docker Desktop
# On Linux: sudo systemctl start docker
```

## Troubleshooting Installation

### Command Not Found

If `vibekit` command is not found after global installation:

<Tabs>
  <Tab title="npm">
    ```bash theme={"dark"}
    # Check npm global bin directory
    npm config get prefix

    # Add to PATH (example for macOS/Linux)
    export PATH="$(npm config get prefix)/bin:$PATH"

    # Make permanent by adding to ~/.bashrc or ~/.zshrc
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"dark"}
    # Check yarn global bin directory
    yarn global bin

    # Add to PATH
    export PATH="$(yarn global bin):$PATH"
    ```
  </Tab>
</Tabs>

### Permission Errors

If you encounter permission errors during global installation:

```bash theme={"dark"}
# Option 1: Use a Node version manager (recommended)
# Install nvm: https://github.com/nvm-sh/nvm
nvm install node
npm install -g vibekit

# Option 2: Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g vibekit
```

### Docker Not Running (Optional)

If you want to use Docker sandbox and see Docker-related errors:

```bash theme={"dark"}
# Check if Docker is installed
docker --version

# Check if Docker daemon is running
docker ps

# Start Docker
# macOS: Open Docker Desktop application
# Linux: sudo systemctl start docker
# Windows: Start Docker Desktop
```

### Agent Not Found

If you see "command not found" errors for Claude or Gemini:

```bash theme={"dark"}
# For Claude Code CLI
npm install -g @anthropic/claude-code

# Verify installation
claude --version

# Set up global aliases (optional)
vibekit setup-aliases
```

## Platform-Specific Notes

### macOS

* Docker Desktop is recommended
* May need to grant terminal permissions for Docker
* Homebrew users can install Node.js with `brew install node`

### Linux

* Add your user to the docker group: `sudo usermod -aG docker $USER`
* Log out and back in for group changes to take effect
* Some distributions may require `sudo` for global npm installs

### Windows

* Use WSL2 for best compatibility
* Docker Desktop with WSL2 backend is recommended
* Run commands in WSL2 terminal, not Command Prompt

## Updating the CLI

To update to the latest version:

<CodeGroup>
  ```bash npm theme={"dark"}
  npm update -g vibekit
  ```

  ```bash yarn theme={"dark"}
  yarn global upgrade vibekit
  ```

  ```bash npx theme={"dark"}
  # npx always uses the latest version
  npx vibekit@latest
  ```
</CodeGroup>

## Uninstalling

To remove the CLI:

<CodeGroup>
  ```bash npm theme={"dark"}
  npm uninstall -g vibekit
  ```

  ```bash yarn theme={"dark"}
  yarn global remove vibekit
  ```
</CodeGroup>

## Next Steps

After installation, you're ready to:

1. [Configure settings](/cli/configuration-files) with `vibekit`
2. [Run your first agent](/cli/quick-reference) with `vibekit claude "Hello world"`
3. [Set up monitoring](/cli/quick-reference) with `vibekit dashboard`

For a quick overview of all commands, see the [Quick Reference](/cli/quick-reference).