Agentic AI Home Lab Beginners Guide

Created using Perplexity AI

Agentic AI Home Lab on Proxmox

A step‑by‑step guide (from zero to working AI agents in Docker) written from the perspective of a recent computer science graduate.

1. What You Will Build

By the end of this guide you will have:

2. Prerequisites

You do not need prior experience with Proxmox, Docker, or AI agents. You should have:

Accounts / software:

3. Proxmox VE Installation

3.1 Downloading Proxmox

  1. Go to the Proxmox VE download page.
  2. Download the latest Proxmox VE ISO.
  3. Use a tool such as Rufus (Windows) or dd (Linux/macOS) to create a bootable USB.

3.2 Installing Proxmox on Bare Metal

  1. Boot your server from the USB.
  2. Choose “Install Proxmox VE”.
  3. Follow the wizard:
    • Target disk: your main SSD/NVMe.
    • Country, time zone, keyboard: configure as appropriate.
    • Password: choose a strong root password and record it.
    • Management network: typically your main NIC with DHCP.

  4. After installation, the console will show a URL, for example:

    • https://192.168.1.50:8006
  5. On your laptop, open that URL and accept the browser’s TLS warning.

4. First Steps in Proxmox

4.1 Logging In

You will land on the Proxmox web UI.

4.2 Basic Proxmox Concepts

For this guide, we will:

5. Create the Ubuntu Docker VM

5.1 Download an Ubuntu Server ISO

  1. Download Ubuntu Server LTS ISO.
  2. In the Proxmox UI:
    • Select your node → “local” storage → “ISO Images” → “Upload”.
    • Upload the Ubuntu ISO.

5.2 Create the VM

  1. Click “Create VM”.
  2. General:
    • Node: your Proxmox node.
    • VM ID: automatic or pick one (e.g., 100).
    • Name: ubuntu-docker.
  3. OS:
    • ISO Image: select your Ubuntu Server ISO.
    • Type: Linux.
  4. System:
    • Leave default for a first build or enable QEMU/UEFI if you prefer.
  5. Disks:
    • Bus/Device: scsi.
    • Disk size: 64–128 GB or more depending on your usage.
  6. CPU:
    • 2–4 cores.
  7. Memory:
    • 4–8 GB (more if you will run many containers).
  8. Network:
    • Bridge: vmbr0 (default bridge to your LAN).
  9. Finish and start the VM.

5.3 Install Ubuntu in the VM

  1. Open the VM console in Proxmox.
  2. Follow the Ubuntu installer:
    • Language, keyboard.
    • Install Ubuntu Server.
    • Disk: use entire virtual disk.
    • Create a user, for example:
      • Username: dev.
    • Enable OpenSSH server.
  3. Reboot into the installed system.

6. SSH Access and Basic Setup

6.1 Find VM IP Address

In the VM console:

ip a

Look for an inet address on ens18 or similar, such as 192.168.1.101/24.

6.2 SSH from Your Laptop

From your laptop/desktop:

ssh dev@192.168.1.101

Accept the host key and log in with your password.

6.3 System Updates

sudo apt update
sudo apt upgrade -y
sudo reboot

Reconnect via SSH after reboot.

7. Install Docker and Docker Compose

7.1 Install Docker Engine

On Ubuntu VM:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify:

docker run hello-world

7.2 Install Docker Compose (v2 CLI)

Docker on Ubuntu now includes Docker Compose as docker compose. Test:

docker compose version

8. Optional: Install Portainer

Portainer is a web UI to manage Docker containers.

docker volume create portainer_data

docker run -d \
  -p 8000:8000 \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Access Portainer at:

9. Agentic AI Concepts (High Level)

Before deployment, understand key ideas:

We will start with:

Then you can expand to multi-agent workflows.

10. Choose an Agent Framework

You can pick any of the popular frameworks. Three common choices:

For a first build, pick one and stay consistent through this guide. The steps below use a generic “Python agent service” pattern that works for all three with small adjustments.

11. Create a Project Structure

On your Ubuntu VM (or cloned from GitHub), create a directory:

mkdir -p ~/agent-lab
cd ~/agent-lab

Example structure:

agent-lab/
  docker-compose.yml
  agent-service/
    Dockerfile
    requirements.txt
    app.py

12. Write a Minimal Agent Service (Python)

12.1 requirements.txt

Example for a generic agent with OpenAI-compatible client:

fastapi
uvicorn[standard]
openai
langchain

Replace or extend with your chosen framework, for example langgraph or crewai.

12.2 app.py (Simple HTTP Agent)

from fastapi import FastAPI
from pydantic import BaseModel
from openai import OpenAI
import os

app = FastAPI()

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

class Task(BaseModel):
    prompt: str

@app.post("/agent")
async def run_agent(task: Task):
    # Simple single-call agent (no tools) as a starting point
    response = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=[
            {"role": "system", "content": "You are a helpful coding assistant in a homelab."},
            {"role": "user", "content": task.prompt},
        ],
    )
    return {"result": response.choices[0].message.content}

This is intentionally minimal. Later you can:

13. Dockerfile for the Agent

agent-service/Dockerfile:

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONUNBUFFERED=1

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

EXPOSE 8000

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

14. Docker Compose Configuration

docker-compose.yml in agent-lab:

version: "3.9"

services:
  agent-service:
    build: ./agent-service
    container_name: agent-service
    ports:
      - "8000:8000"
    environment:
      OPENAI_API_KEY: "${OPENAI_API_KEY}"
    restart: unless-stopped

Create a .env file in agent-lab (never commit secrets):

cat <<EOF > .env
OPENAI_API_KEY=your-real-api-key-here
EOF

15. Build and Run the Agent Service

From ~/agent-lab:

docker compose build
docker compose up -d

Check status:

docker ps

You should see agent-service running and listening on port 8000.

16. Test the Agent API

From your laptop (replace IP):

curl -X POST "http://192.168.1.101:8000/agent" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a short Dockerfile that prints Hello World and explain each line."}'

You should receive JSON with a text response.

17. Evolving Towards Agentic Behavior

The minimal service above is a simple “stateless” chat wrapper. To make it agentic, incrementally add:

At the framework level this often means:

18. Example: Add a Simple Tool (Conceptual)

Here is a conceptual pattern (pseudo-code style) for adding a tool:

import subprocess
from typing import List

def list_files() -> List[str]:
    files = subprocess.check_output(["ls", "-1"], text=True).splitlines()
    return files

Then expose list_files to your LLM using your agent framework’s tool mechanism.

Note: For safety, start with read-only tools and limit directories.

19. Using the Agent Lab to Test Docker Containers

Your home lab is now ready to:

Example workflow:

  1. Clone a containerized app into ~/projects/app1.
  2. Use your agent to:
    • Analyze its Dockerfile.
    • Propose improvements.

  3. Build and run it with:

    docker compose build
docker compose up -d

  4. Capture logs:

    docker logs <container-name>
  5. Feed relevant logs back to the agent for debugging help.

20. Monitoring and Maintenance

20.1 Basic Docker Commands

20.2 Backups

21. Security Basics

22. Where to Go Next

Now that you have the basics:

23. Appendix: Common Commands Cheat Sheet

Proxmox

Ubuntu VM

Docker

End of Markdown guide (v1).