Skip to content

Quickstart

Prerequisites

  • Python 3.10+
  • Docker or Podman (running)

Using Podman instead of Docker

VibePod can use Podman's Docker-compatible API socket and applies the necessary rootless user-namespace settings (keep-id) so workspace file permissions work correctly.

If DOCKER_HOST is not set, VibePod asks Podman for its socket location and uses it automatically — on macOS this matters because the machine socket path changes with $TMPDIR at machine-start time. You only need to make sure the socket exists:

systemctl --user enable --now podman.socket

podman machine init   # first time only
podman machine start

Setting DOCKER_HOST explicitly still works and takes precedence:

# Linux
export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
# macOS
export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')

The socket path is dynamic on macOS

The Podman machine socket lives under $TMPDIR, which changes between machine starts — a hardcoded DOCKER_HOST will break after a reboot. If you set it manually, always compute it via podman machine inspect as above (e.g. in your ~/.zshrc).

Container DNS required

VibePod routes agent traffic through a vibepod-proxy container. The agent resolves the proxy by container name over the vibepod-network network, which requires DNS to be enabled.

If your Podman installation uses the CNI network backend, you must install the dnsname plugin — otherwise DNS is disabled and the proxy will be unreachable.

sudo dnf install podman-plugins

sudo apt install golang-github-containernetworking-plugin-dnsname

sudo pacman -S podman-dnsname

After installing, recreate the network so DNS takes effect:

podman network rm vibepod-network 2>/dev/null
podman network create vibepod-network

Verify with:

podman network inspect vibepod-network --format '{{.DNSEnabled}}'
# Should print: true

Alternatively, switch to the Netavark network backend (Podman 4.0+), which includes DNS out of the box. See podman info --format '{{.Host.NetworkBackend}}' to check your current backend.

Install

pip install vibepod

brew install vibepod/vibepod/vibepod

conda install -c conda-forge vibepod
# or
mamba install -c conda-forge vibepod

pixi global 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 or Podman 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.

Note

Closing the terminal window does not stop the container — the agent keeps running in the background. Use vp list --running to see it and vp attach <container> to rejoin the session. See Reattaching a terminal for details.

Shortcuts

You can start agents with the full agent command. Most agents also have a single-letter shortcut; Pi uses vp pi because vp p is assigned to Copilot, Agy uses vp n, Tau uses vp t, Jcode uses vp j, Freebuff uses vp fb, and Qwen uses vp q. DeepSeek Harness uses vp ds and opens a Web UI — the URL is printed after start.

vp claude   # full name
vp c        # shortcut
vp run c    # shortcut with run also works

Point at a different workspace

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

vp run claude -w ~/other-project

Pass arguments to the agent

Arguments after the agent name are forwarded to the agent command inside the container:

vp run <agent> <agent-args>

When forwarding flags to the agent, use -- to stop VibePod option parsing:

vp run <agent> -- <agent-flag> <value>

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

Check which agents are running:

vp list --running

Stop it later with:

vp stop claude

For more details on detached mode workflows, see Agents > Detached mode.

Add reusable skills

Skills are reusable prompt/recipe folders that supported agents can discover at runtime. Install one with:

vp skills add github:vibepod/vibepod-skills//skills/researcher --scope user

Use --scope local to install into the current project, or omit it to use the normal scope auto-detection. See Skills for scopes, GitHub URL installs, bundles, and update/sync behavior.

Browse example skills and future VibePod-specific skills in VibePod/vibepod-skills.

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