Skip to content

Commit 019cb23

Browse files
nezharnezhar
committed
Extend docs for podman
1 parent 6077311 commit 019cb23

5 files changed

Lines changed: 113 additions & 3 deletions

File tree

‎docs/configuration.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ version: 1
1818
# Agent to run when no argument is given to `vp run`
1919
default_agent: claude
2020

21+
# Container runtime: auto | docker | podman (default: auto)
22+
# See docs/podman.md for setup instructions
23+
container_runtime: auto
24+
2125
# Pull the latest image before every run (default: true)
2226
# Can be overridden per agent with agents.<agent>.auto_pull
2327
auto_pull: true
@@ -105,6 +109,7 @@ These variables override the corresponding config keys without editing any file:
105109
106110
| Variable | Config key | Example |
107111
|---|---|---|
112+
| `VP_CONTAINER_RUNTIME` | `container_runtime` | `VP_CONTAINER_RUNTIME=podman` |
108113
| `VP_DEFAULT_AGENT` | `default_agent` | `VP_DEFAULT_AGENT=gemini` |
109114
| `VP_AUTO_PULL` | `auto_pull` | `VP_AUTO_PULL=true` |
110115
| `VP_LOG_LEVEL` | `log_level` | `VP_LOG_LEVEL=debug` |

‎docs/index.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# VibePod
22

3-
**One CLI for all AI coding agents — running in Docker containers.**
3+
**One CLI for all AI coding agents — running in Docker or Podman containers.**
44

5-
VibePod (`vp`) lets you run any supported AI coding agent in an isolated Docker container, pointed at any workspace directory, with a single command. Agent credentials, config, and session logs are persisted across runs without touching your host environment.
5+
VibePod (`vp`) lets you run any supported AI coding agent in an isolated container, pointed at any workspace directory, with a single command. Agent credentials, config, and session logs are persisted across runs without touching your host environment.
66

77
## Why VibePod?
88

@@ -26,6 +26,7 @@ VibePod (`vp`) lets you run any supported AI coding agent in an isolated Docker
2626
## Next Steps
2727

2828
- [**Quickstart**](quickstart.md) — install and run your first agent in two minutes.
29+
- [**Using Podman**](podman.md) — set up Podman as an alternative to Docker.
2930
- [**Development**](development.md) — local setup, tests, and docs workflow.
3031
- [**Agents**](agents/index.md) — per-agent setup and credential instructions.
3132
- [**Configuration**](configuration.md) — full reference for global and project-level config.

‎docs/podman.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Using Podman
2+
3+
VibePod works with [Podman](https://podman.io/) as an alternative to Docker. Rootless Podman is fully supported — no `sudo` required.
4+
5+
## Prerequisites
6+
7+
- Podman 4.0+
8+
- The rootless Podman socket enabled:
9+
10+
```bash
11+
systemctl --user enable --now podman.socket
12+
```
13+
14+
Verify the socket is active:
15+
16+
```bash
17+
systemctl --user status podman.socket
18+
```
19+
20+
## Selecting the runtime
21+
22+
VibePod auto-detects available runtimes. If only Podman is installed, it is used automatically. When both Docker and Podman are available, VibePod prompts you to choose (and remembers your choice).
23+
24+
You can also set the runtime explicitly using any of the methods below. They are listed in priority order — the first one found wins:
25+
26+
### 1. CLI flag
27+
28+
Pass `--runtime` to any command:
29+
30+
```bash
31+
vp run claude --runtime podman
32+
vp stop --all --runtime podman
33+
vp logs start --runtime podman
34+
```
35+
36+
### 2. Environment variable
37+
38+
Set `VP_CONTAINER_RUNTIME` to skip the prompt entirely:
39+
40+
```bash
41+
export VP_CONTAINER_RUNTIME=podman
42+
vp run claude
43+
```
44+
45+
This is useful in CI or shell profiles where you always want a specific runtime.
46+
47+
### 3. Global config
48+
49+
Add `container_runtime` to `~/.config/vibepod/config.yaml`:
50+
51+
```yaml
52+
container_runtime: podman
53+
```
54+
55+
When VibePod prompts you to choose a runtime interactively, it saves your answer here automatically so you are not asked again.
56+
57+
Set it back to `auto` to re-enable detection:
58+
59+
```yaml
60+
container_runtime: auto
61+
```
62+
63+
## How it works
64+
65+
VibePod uses the standard [Docker SDK for Python](https://docker-py.readthedocs.io/) to communicate with Podman through its Docker-compatible REST API. No additional Python packages are needed.
66+
67+
The rootless Podman socket is discovered via `$XDG_RUNTIME_DIR/podman/podman.sock` (falling back to `/run/user/<uid>/podman/podman.sock`). The rootful socket at `/run/podman/podman.sock` is only used when running as root.
68+
69+
## Known limitations
70+
71+
### Interactive attach
72+
73+
The `attach_socket()` call in Podman's Docker-compat layer has minor gaps under rootless mode. If you experience rendering issues while attached to a container, try running with `--detach` and using `podman attach` directly:
74+
75+
```bash
76+
vp run claude -d
77+
podman attach vibepod-claude-<id>
78+
```
79+
80+
### Volume permissions
81+
82+
Rootless Podman uses user-namespace remapping: your host UID is mapped to root inside the container, while other UIDs are mapped to subordinate ranges. Container images that drop privileges via `su` or `gosu` may encounter permission errors on bind-mounted files.
83+
84+
VibePod handles this automatically for its own managed directories (agent config, proxy data, CA certificates) by adjusting permissions before and during container startup. Your workspace directory is mounted as-is and is not modified.
85+
86+
If you still see permission errors on workspace files, adjust permissions for the owner first. For collaborative setups that share a group, you can optionally grant group write access as well. Avoid making the workspace world-writable.
87+
88+
```bash
89+
chmod -R u+rwX ~/my-project
90+
# Optional for shared group workspaces:
91+
chmod -R g+rwX ~/my-project
92+
```
93+
94+
### Rootful Podman
95+
96+
VibePod targets rootless Podman. The rootful socket (`/run/podman/podman.sock`) is only probed when running as root. If you need rootful Podman as a non-root user, set `DOCKER_HOST` explicitly:
97+
98+
```bash
99+
export DOCKER_HOST=unix:///run/podman/podman.sock
100+
```
101+
102+
Note that this will require elevated privileges (e.g. via `sudo` or polkit).

‎docs/quickstart.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Prerequisites
44

55
- Python 3.10+
6-
- Docker (running)
6+
- Docker **or** [Podman](podman.md) (running)
77

88
## Install
99

@@ -110,5 +110,6 @@ This starts a Datasette container and opens `http://localhost:8001` in your brow
110110
## Next Steps
111111

112112
- [Configure an agent](agents/index.md) — set API keys and per-agent options.
113+
- [Using Podman](podman.md) — set up Podman as an alternative to Docker.
113114
- [Configuration reference](configuration.md) — tune defaults, the proxy, and logging.
114115
- [CLI Reference](cli-reference.md) — every command and flag.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ markdown_extensions:
5050
nav:
5151
- Home: index.md
5252
- Quickstart: quickstart.md
53+
- Using Podman: podman.md
5354
- Development: development.md
5455
- Agents: agents/index.md
5556
- Configuration: configuration.md

0 commit comments

Comments
 (0)