dockpipe

Run any command in a disposable container. Optionally run an action on the result (e.g. commit, export patch).

General-purpose: run tests, one-off scripts, codegen, or AI tools—same flow. Your dir is mounted, your user owns the files, container is gone when done. Not an AI framework; AI is one use case.

---

Try it (15 seconds)

Install: Download the .deb → sudo dpkg -i dockpipe_*_all.deb
Or from source: git clone https://github.com/jamie-steele/dockpipe.git and add bin to your PATH.

First run:

dockpipe -- make test

Runs make test in a clean container. Your current directory is at /work. When it exits, the container is removed. Closing the terminal also tears down the container (attached run). Use -d to run in the background. Same for npm test, cargo test, or any command.

---

What you can do

Use case	Command
Run tests in isolation	dockpipe -- make test
Run a script and commit the result	dockpipe --action examples/actions/commit-worktree.sh -- ./scripts/generate-docs.sh
Pipe stdin	echo "input" | dockpipe -- cmd
AI + commit	dockpipe --template agent-dev --action examples/actions/commit-worktree.sh -- claude -p "Your prompt"

Scaffold your own action: dockpipe action init my-action.sh (or init my-commit.sh --from commit-worktree to copy a bundled one) → then --action my-action.sh.

---

How it works

1. Spawn — Start a container (default: small dev image, built if needed).
2. Run — Execute the command you pass after --.
3. Act — Optionally run a script after the command (e.g. commit, notify).

You pick the image, the command, and the action. No workflow engine—just one primitive you compose.

Persistent data: By default dockpipe mounts a named volume dockpipe-data at /dockpipe-data and sets HOME there so tool state (e.g. first-time Claude login) persists. Use --data-vol <name> or --data-dir /path to change where; --no-data to disable. Override HOME with --env HOME=... if a tool needs a different home. If a tool (e.g. Claude) exits immediately with the default volume, try --no-data or --reinit (removes the named volume so the next run gets a fresh one).

---

Why not just docker run?

Same isolation, less boilerplate. You’d otherwise write:

docker run --rm -v "$(pwd):/work" -w /work -u "$(id -u):$(id -g)" some-image make test

dockpipe does that by default and adds: action phase (run then act in one go), templates (--template dev / agent-dev), pipe-friendly CLI. Files created in the container are owned by you (UID/GID passed through).

---

Install (details)

Platform	How
Linux	Releases → sudo dpkg -i dockpipe_*_all.deb
macOS	Clone repo, add bin to PATH. Requires Bash + Docker.
Windows	Not supported; WSL + source may work.

Requirements: Bash, Docker. More in docs/install.md.

---

Usage

dockpipe [options] -- <command> [args...]
dockpipe action init [--from <bundled>] <filename>

Option	Description
--image <name>	Docker image (default: dockpipe-base-dev).
--template <name>	Preset: base-dev, dev, agent-dev (or claude).
--action <script>	Script run inside container after the command.
--workdir <path>	Host path mounted at /work (default: current dir).
--data-vol <name>	Named volume for persistent data (default: dockpipe-data). Same volume each run = reusable agent environment.
--data-dir <path>	Bind mount host path for persistent data (e.g. $HOME/.dockpipe). Mounted at /dockpipe-data; HOME set there.
--no-data	Do not mount the data volume (minimal run).
--reinit	Remove the named data volume before running (fresh volume). Prompts to confirm; use -f to skip.
-f, --force	With --reinit, skip confirmation (warning still shown).
--mount, --env	Extra volumes or env vars.
-d, --detach	Run container in background; don't attach. Container stays up until command exits.
--help	Help.

---

Examples

Generic:

dockpipe -- ls -la
dockpipe -- bash -c "npm test"
dockpipe --template dev -- make test

Run script then commit:

dockpipe --action examples/actions/commit-worktree.sh -- ./my-script.sh

AI (agent-dev template) + commit:

cd /path/to/repo
dockpipe --template agent-dev --action examples/actions/commit-worktree.sh \
  --env "DOCKPIPE_COMMIT_MESSAGE=agent: my task" \
  -- claude --dangerously-skip-permissions -p "Your prompt"

Run in background (detach): close terminal and container keeps running until the command exits; use docker logs <id> or docker attach <id>:

dockpipe -d --template agent-dev -- claude -p "review this"

Resume a previous Claude session (state lives in the default data volume):

dockpipe --template agent-dev -- claude --resume <session-id> --dangerously-skip-permissions

Chained (each step in a fresh container):

dockpipe -- make lint && dockpipe -- make test && dockpipe -- make build

Full runnable examples: chained non-AI · chained multi-AI · Claude worktree · Codex worktree

---

Templates

Template	Description
base-dev	Light: git, curl, bash, ripgrep, jq.
dev	base-dev + build-essential, ssh, etc.
agent-dev	Node + Claude Code (AI/agent workflows). claude is an alias.

---

Actions

Scripts that run inside the container after your command. They get DOCKPIPE_EXIT_CODE and DOCKPIPE_CONTAINER_WORKDIR. Create one: dockpipe action init my-action.sh, or clone a bundled one to customize: dockpipe action init my-commit.sh --from commit-worktree. Bundled: commit-worktree, export-patch, print-summary.

---

Docs & repo

• Blog: Run, Isolate, and Act
• Architecture · Install · AGENTS.md
• Tests: bash tests/run_tests.sh (from repo root). Integration tests (Docker + agent-dev): integration-tests/README.md → bash integration-tests/run.sh

License: Apache-2.0. See LICENSE.