Skip to content

VMPilot Installation Guide

This guide provides step-by-step instructions for installing VMPilot in your environment. VMPilot comes with Open WebUI bundled in the Docker container, providing a seamless, integrated installation experience with a powerful web interface.

[!CAUTION] Only run VMPilot if you understand the security implications of running arbitrary commands in your virtual machine. Never run this directly on your personal machine. You are letting the AI/LLM run commands in your machine which can be dangerous.

Prerequisites

Before you begin, ensure you have: - Docker installed on your system - Basic familiarity with Docker and Linux - For secure remote access, complete the DNS and SSL Setup before proceeding

VMPilot is available as a Docker container from GitHub Container Registry (ghcr.io). This container includes both VMPilot and Open WebUI pre-configured to work together.

Docker Installation Steps

  1. Download the installation script, review it, and then run it:
Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Download the installation script
curl -sSL https://raw.githubusercontent.com/drorm/vmpilot/main/bin/install.sh -o install_vmpilot.sh

# Review the script and make any necessary changes
# For example, you may want to change the target directory (VMPILOT_DIR)
nano install_vmpilot.sh

# Make the script executable
chmod +x install_vmpilot.sh

# Run the installation script
./install_vmpilot.sh

This script will: - Create the necessary directories (default is $HOME/.vmpilot/) - Pull the latest VMPilot image from GitHub Container Registry - Start the container with proper configuration - Copy the default configuration file

  1. Verify the container is running:

    Bash
    1
    docker ps | grep vmpilot

  2. Access the web interface:

  3. Open your browser and navigate to http://localhost:8080
  4. Follow the steps in Using the Web UI to complete setup

Port Configuration

The VMPilot Docker container exposes two main ports: - Port 8080: Open WebUI interface - Port 9099: VMPilot pipeline server (internal communication)

If you need to change these ports, modify the port mapping in your Docker run command:

Bash
1
2
3
4
5
docker run -d \
  -p <custom-webui-port>:8080 \
  -p <custom-pipeline-port>:9099 \
  ... other options ...
  ghcr.io/drorm/vmpilot:latest

1.2 Manual Installation

1.2.1 Virtual Machine Setup

  • Set up your Docker virtual machine according to your requirements
  • For enhanced security, install gvisor and configure your container runtime to use it

1.2.2 Install OpenWebUI Pipelines

OpenWebUI Pipelines is required for VMPilot integration.

Bash
1
2
cd ~
git clone https://github.com/open-webui/pipelines

This will clone the repository to your home directory. This is the default location for VMPilot to look for the pipelines.

1.2.3 Install dependencies:

Bash
1
pip install -r requirements.txt
You don't need to run the pipelines server, as VMPIlot will run it.

1.2.4 Installing VMPilot

1.2.5 Server Installation

Clone the VMPilot repository:

Bash
1
2
3
cd ~
git clone https://github.com/drorm/vmpilot.git
cd vmpilot

Install dependencies:

Bash
1
pip install -r requirements.txt

Set up your credentials. The defaults are: - Anthropic: ~/.anthropic/api_key - OpenAI: ~/.openai

1.2.6 Configuration Setup

For CLI usage: 1. Set up your password (required for CLI mode) 2. Review vmpilot/src/vmpilot/config.ini - the defaults will work for most setups 3. Optionally, you can set the environment variable VMPILOT_CONFIG to use a custom configuration file

1.2.7 Start VMPilot

Bash
1
~/vmpilot/bin/run.sh

2. First-Time Setup

After installing VMPilot, you'll need to complete a few setup steps to get started.

2.1 Accessing the Web Interface

  1. After starting the VMPilot container, the Open WebUI interface is automatically available at:

    Text Only
    1
    http://localhost:8080

  2. When you first access the interface, you'll need to create a user account. The first user created automatically becomes the admin.

2.2 Configuring API Keys

To use VMPilot with your preferred LLM provider:

  1. Click on your username in the bottom left corner
  2. Select "Admin Panel"
  3. Navigate to the "Pipelines" tab
  4. Enter your API keys for OpenAI, Anthropic, or both
  5. Click "Save"

The connection between Open WebUI and VMPilot is pre-configured in the container, so you don't need to set up the connection manually.

For more detailed information on using the web interface, see the Using Open WebUI guide.

3. Verification

To verify your installation is working correctly:

  1. Open the web interface in your browser (http://localhost:8080)
  2. Log in with the user account you created
  3. Create a new conversation
  4. Choose one of the VMPilot models (Claude is recommended)
  5. Try a simple command like "Show me the contents of /home"
  6. VMPilot should execute the command and return the results

If the command executes successfully, your installation is working properly.

4. Troubleshooting

5. Project Configuration Setup

After installing VMPilot, you'll want to set up project-specific configuration for each of your projects.

5.1 Project Directory Structure

When you start using VMPilot with a new project, it will check for the existence of the .vmpilot directory structure:

Text Only
1
2
3
4
your-project/
└── .vmpilot/
    └── prompts/
        └── project.md

5.2 Initial Project Setup

VMPilot will guide you through the setup process when you first use it with a project:

  1. Start a chat session in your project directory:Simply make a request like "do pwd"
  2. VMPilot will detect if the .vmpilot directory structure is missing
  3. You'll be presented with options:
  4. Create standard project files from a template
  5. Skip project setup
  6. When you choose to create standard project files, VMPilot will offer to:
  7. Analyze existing files and create a customized project description
  8. Let you do it manually

5.3 Project Description File

The project.md file contains essential information about your project that's included in the system prompt for each conversation. This helps VMPilot understand your project's context, structure, and requirements.

For more details on project configuration, see the Project Plugin documentation.

Common installation issues and solutions:

Container Issues

  1. Container fails to start:
  2. Check Docker logs: docker logs vmpilot
  3. Verify Docker is running: systemctl status docker
  4. Ensure you have sufficient disk space: df -h

  5. Check for port conflicts: netstat -tuln | grep 8080

  6. Container starts but services are unavailable:

  7. Check service status: docker exec vmpilot supervisorctl status
  8. View logs for specific services:
    Bash
    1
2
    docker exec vmpilot tail -f /app/data/logs/vmpilot.log
docker exec vmpilot tail -f /app/data/logs/open-webui.log
  9. Restart services if needed: docker exec vmpilot supervisorctl restart all

Access Issues

  1. Cannot access web interface:
  2. Verify the container is running: docker ps | grep vmpilot
  3. Check if port 8080 is accessible: curl -I http://localhost:8080
  4. Ensure no firewall is blocking access: sudo ufw status
  5. Try accessing from the host directly: http://127.0.0.1:8080

Configuration Issues

  1. API key problems:
  2. Ensure you've entered valid API keys in the Open WebUI Admin Panel
  3. Check for error messages in the web interface

  4. Verify your API keys work with the respective services

  5. Model not found:

  6. Go to Admin Panel > Pipelines and verify your API keys are correctly entered
  7. When using a workspace, edit the workspace and make sure the pipeline is selected
  8. Check if the model is available from your provider

Resource Issues

  1. Performance problems:
  2. Check container resource usage: docker stats vmpilot
  3. Verify the host has sufficient resources: free -h and top
  4. Consider increasing container resource limits if necessary