# VibePod Specification

**Version:** 1.0.0  
**Date:** February 2026  
**Language:** Python 3.10+  
**CLI Framework:** Typer  

---

## Project Overview

VibePod is a unified CLI tool for running AI coding agents in isolated Docker containers.

### Goals

1. **Unified interface** - One CLI (`vp`) for all agents
2. **Container isolation** - Each agent runs in Docker
3. **Skills management** - Via AGENTS.lock integration
4. **API logging** - Datasette-powered analytics
5. **Cross-platform** - macOS, Linux, Windows

### Non-Goals

- Building the container images (handled by nezhar/*-container repos)
- Replacing AGENTS.lock (we integrate, not reimplement)
- Performance optimization (readability over speed)

---

## Brand Assets

| Platform | Namespace | Status |
|----------|-----------|--------|
| Domain | vibepod.dev | ✅ |
| GitHub | github.com/VibePod | ✅ |
| Docker Hub | hub.docker.com/u/vibepod | ✅ |
| X/Twitter | @vibepod_dev | ✅ |
| Discord | VibePod server | ✅ |
| Bluesky | @vibepod.dev (via DNS) | 🔒 |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        User                                      │
│                          │                                       │
│                          ▼                                       │
│                    ┌───────────┐                                │
│                    │  vp CLI   │  (Python/Typer)                │
│                    └─────┬─────┘                                │
│                          │                                       │
│          ┌───────────────┼───────────────┐                      │
│          ▼               ▼               ▼                      │
│   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│   │   Docker    │ │  AGENTS.    │ │  Datasette  │              │
│   │   SDK       │ │  lock       │ │  (logging)  │              │
│   │  (Python)   │ │  (Python)   │ │  (Python)   │              │
│   └──────┬──────┘ └─────────────┘ └─────────────┘              │
│          │                                                       │
│          ▼                                                       │
│   ┌─────────────────────────────────────────────┐               │
│   │           Docker Hub: vibepod/*             │               │
│   │                                             │               │
│   │  vibepod/claude    vibepod/gemini          │               │
│   │  vibepod/opencode  vibepod/devstral        │               │
│   │  vibepod/auggie    vibepod/datasette       │               │
│   └─────────────────────────────────────────────┘               │
└─────────────────────────────────────────────────────────────────┘
```

---

## Repository Structure

### VibePod Organization

| Repository | Purpose |
|------------|---------|
| `VibePod/vibepod` | Main CLI tool (this spec) |
| `VibePod/docs` | Documentation site (vibepod.dev) |
| `VibePod/skills` | Official skills collection |

### Container Repositories

| Repository | Docker Image |
|------------|--------------|
| `nezhar/claude-container` | `vibepod/claude` |
| `nezhar/gemini-container` | `vibepod/gemini` |
| `nezhar/opencode-container` | `vibepod/opencode` |
| `nezhar/devstral-container` | `vibepod/devstral` |
| `nezhar/auggie-container` | `vibepod/auggie` |

### External Dependencies

| Package | Purpose |
|---------|---------|
| `luml-ai/AGENTS.lock` | Skills & config sync |

---

## Supported Agents

| Agent | Provider | Image | Config Dir |
|-------|----------|-------|------------|
| claude | Anthropic | `vibepod/claude` | `~/.config/vibepod/agents/claude` |
| gemini | Google | `vibepod/gemini` | `~/.config/vibepod/agents/gemini` |
| opencode | OpenAI | `vibepod/opencode` | `~/.config/vibepod/agents/opencode` |
| devstral | Mistral | `vibepod/devstral` | `~/.config/vibepod/agents/devstral` |
| auggie | Augment | `vibepod/auggie` | `~/.config/vibepod/agents/auggie` |

---

## Installation Methods

### Primary: pipx

```bash
pipx install vibepod
```

### Secondary: pip

```bash
pip install vibepod
```

### Tertiary: Binary (via PyInstaller)

```bash
# macOS/Linux
curl -fsSL https://vibepod.dev/install.sh | bash

# Windows
irm https://vibepod.dev/install.ps1 | iex
```

### Development

```bash
git clone https://github.com/VibePod/vibepod
cd vibepod
pip install -e ".[dev]"
```

---

## Links

| Resource | URL |
|----------|-----|
| Website | https://vibepod.dev |
| GitHub | https://github.com/VibePod/vibepod |
| Docker Hub | https://hub.docker.com/u/vibepod |
| PyPI | https://pypi.org/project/vibepod |
| AGENTS.lock | https://github.com/luml-ai/AGENTS.lock |
