Skip to content

Quickstart

Prerequisites

  • Python 3.10+
  • Docker (running)

Install

pip install vibepod

Verify the installation:

vp version

Run your first agent

Navigate to the project you want to work on, then run an agent:

cd ~/my-project
vp run claude

VibePod will:

  1. Pull the agent image if not already present.
  2. Create a dedicated Docker network (vibepod-network).
  3. Mount your current directory as the workspace inside the container.
  4. Start the agent container and attach your terminal to it.

Press Ctrl+C to stop the container when you are done.

Shortcuts

Every agent has a single-letter shortcut so you don't have to type run:

vp c   # claude
vp g   # gemini
vp o   # opencode
vp d   # devstral
vp a   # auggie
vp p   # copilot
vp x   # codex

Point at a different workspace

Use -w / --workspace to target any directory:

vp run claude -w ~/other-project

Bootstrap a project config

Create a project-level config file that you can extend later:

vp config init

This creates .vibepod/config.yaml in your current directory with a minimal starter:

version: 1

Add a specific agent block into the project config with:

vp config init claude

If that agent is already configured under agents, the command exits without changing the file.

Run in the background

Use -d / --detach to start the container without attaching your terminal:

vp run claude -d

Stop it later with:

vp stop claude

View the session log UI

VibePod records every session and proxied HTTP request. Open the Datasette UI with:

vp logs start

This starts a Datasette container and opens http://localhost:8001 in your browser.

Next Steps