Agents¶

VibePod manages each agent as a Docker container. Credentials and config are persisted to ~/.config/vibepod/agents/<agent>/ on your host and mounted into the container on every run, so you only need to authenticate once.

Supported Agents¶

Agent	Provider	Shortcut	Image
`claude`	Anthropic	`vp c`	`nezhar/claude-container:latest`
`gemini`	Google	`vp g`	`nezhar/gemini-container:latest`
`opencode`	OpenAI	`vp o`	`nezhar/opencode-cli:latest`
`devstral`	Mistral	`vp d`	`nezhar/devstral-cli:latest`
`auggie`	Augment Code	`vp a`	`nezhar/auggie-cli:latest`
`copilot`	GitHub	`vp p`	`nezhar/copilot-cli:latest`
`codex`	OpenAI	`vp x`	`nezhar/codex-cli:latest`

First run & authentication¶

Start any agent for the first time with vp run <agent>. The container will prompt you to authenticate (browser OAuth, API key entry, or device flow depending on the provider). Once authenticated, credentials are written to the persisted config directory and reused on subsequent runs.

Overriding the image¶

You can point VibePod at a custom image via an environment variable:

VP_IMAGE_CLAUDE=myorg/my-claude:dev vp run claude

Or permanently via your global config:

agents:
  claude:
    image: myorg/my-claude:dev

Image customization workflows¶

VibePod has a fixed set of supported agent IDs (claude, gemini, opencode, devstral, auggie, copilot, codex). Image customization means changing the image used for one of those IDs.

1. Extend an existing image for an agent¶

Example: add tools to the default Claude image.

Create a Dockerfile that extends the current base image.

# Dockerfile.claude
FROM nezhar/claude-container:latest

# Add project-specific utilities.
RUN apt-get update \
  && apt-get install -y --no-install-recommends ripgrep jq \
  && rm -rf /var/lib/apt/lists/*

Build and tag the derived image.

docker build -f Dockerfile.claude -t myorg/claude-container:with-tools .

Run with the new image (one-off) or set it in config (persistent).

# one-off
VP_IMAGE_CLAUDE=myorg/claude-container:with-tools vp run claude

# ~/.config/vibepod/config.yaml (or .vibepod/config.yaml)
agents:
  claude:
    image: myorg/claude-container:with-tools

2. Add a new image for an agent¶

Example: point opencode at a newly published internal image.

Build/publish your image to a registry (for example registry.example.com/team/opencode:2026-03-01).
Attach that image to the target agent in config.

agents:
  opencode:
    image: registry.example.com/team/opencode:2026-03-01

Start the agent.

vp run opencode

You can also test quickly without editing config:

VP_IMAGE_OPENCODE=registry.example.com/team/opencode:2026-03-01 vp run opencode

Passing environment variables¶

Use -e / --env to inject variables at runtime:

vp run claude -e MY_VAR=value -e ANOTHER=123

Persistent per-agent env vars can also be set in config:

agents:
  claude:
    env:
      MY_VAR: value

Init scripts before startup¶

Use agents.<agent>.init to run shell commands in the container before the agent launches. This is useful for installing extra tools in a custom image workflow.

agents:
  codex:
    init:
      - apt-get update
      - apt-get install -y ripgrep jq

The init commands run on every vp run for that agent and must be idempotent.

Connecting to a Docker Compose network¶

When your workspace contains a docker-compose.yml or compose.yml, VibePod detects it and offers to connect the agent container to an existing network so it can reach your running services.

You can also specify the network explicitly:

vp run claude --network my-compose-network

Individual agents¶

Claude (Anthropic)¶

vp run claude   # or: vp c

Credentials are stored in ~/.config/vibepod/agents/claude/. On first run, Claude's interactive setup will guide you through API key configuration.

Gemini (Google)¶

vp run gemini   # or: vp g

OpenCode (OpenAI)¶

vp run opencode   # or: vp o

Devstral (Mistral)¶

vp run devstral   # or: vp d

Note

Devstral runs under your host user (uid:gid) and requires the linux/amd64 platform. On Apple Silicon, Docker's Rosetta emulation is used automatically.

Auggie (Augment Code)¶

vp run auggie   # or: vp a

Copilot (GitHub)¶

vp run copilot   # or: vp p

Codex (OpenAI)¶

vp run codex   # or: vp x