pi-docker

One safe, flexible Docker tool for the Pi coding agent.

pi-docker replaces long, error-prone Docker command construction with one structured docker_manager tool. It still uses your installed Docker CLI, active Docker context, credential store, Compose plugin, and Buildx plugin.

Install

pi install npm:@kushalkhemka/pi-docker

Reload an already-open Pi session with /reload. New sessions load the package automatically.

You can also install directly from GitHub:

pi install git:github.com/Kushalkhemka/pi-docker

What it manages

• Docker status and contexts
• Containers, images, networks, volumes, inspection, stats, and logs
• Run, disposable run, exec, start, stop, restart, pause, unpause, kill, and remove
• Docker Compose up/down/restart/ps/logs/exec/run/build/pull/config
• Live container, Compose, and Swarm service logs
• Interactive container shell and docker attach
• Docker Swarm nodes, services, scaling, logs, and stacks
• Buildx builders and multi-platform builds
• Interactive registry login and guarded logout
• docker cp, image save/load/import, and container export
• Live Docker events
• Guarded literal-argument fallback for Docker features not modeled directly

Ask Pi naturally

Show Docker status and all stopped containers.

Build this repository as opensec/audit:dev and run it on port 8080.

Run these three PoCs in separate disposable containers. Mount the repository
read-only, disable networking, give each 2 CPUs and 4 GB RAM, and keep their
logs separate.

Follow the api and worker Compose logs live.

Open an interactive shell in the api container as the app user.

Create a two-node Swarm service with the image example/api:1.0.0.

Build and push example/api:1.0.0 for linux/amd64 and linux/arm64 with Buildx.

Interactive actions

The following actions temporarily suspend Pi's TUI and give Docker the real terminal:

• logs_follow
• compose_logs_follow
• Swarm service_logs_follow
• shell and compose_shell
• attach
• events_follow
• registry_login
• interactive_raw

Press Ctrl+C to stop following logs or events. Exit a shell normally. For docker attach, Docker's default detach sequence is Ctrl+P, then Ctrl+Q.

The live stream is displayed directly in your terminal while Pi's TUI is suspended. After the terminal returns to Pi, the model receives only the command's completion status, not a replay of the interactive output.

Interactive actions intentionally require Pi's TUI. They are rejected in print, JSON, and RPC modes.

Isolated PoC execution

Use run_ephemeral for untrusted or independent tests. A safe request looks like:

Run the PoC in a fresh disposable container with the repository mounted
read-only, network disabled, root filesystem read-only, all Linux capabilities
dropped, no-new-privileges enabled, 2 CPUs, and 2 GB memory.

Pi can supply advanced flags with extra_args, for example:

{
  "extra_args": [
    "--cap-drop=ALL",
    "--security-opt=no-new-privileges",
    "--tmpfs=/tmp:rw,noexec,nosuid,size=128m"
  ]
}

Separate detached disposable containers can run concurrently. Multiple exec calls in one container share filesystem, process, and network state and are not isolation.

Safety model

• Docker arguments are passed as literal argument arrays; the extension does not invoke a shell.
• Remove, kill, prune, Docker copy, destructive Swarm/Buildx operations, registry logout, and unrestricted raw operations require confirmation.
• Interactive actions ask before taking over the terminal.
• Environment, build-argument, Swarm-token, and password values are redacted from displayed commands.
• Long output is capped, while logs preserve their newest section.
• Compose configuration does not interpolate environment values unless explicitly requested.

Do not put secrets in model-visible arguments. Prefer interactive registry login, environment files, Docker secrets, or BuildKit secret mounts.

Docker daemon access remains highly privileged. Review SECURITY.md before connecting remote engines or using unrestricted actions.

Development

npm install
npm run check

The tests validate command construction, disposable execution defaults, Compose live logs, Swarm, Buildx, literal raw arguments, output truncation, and secret redaction without requiring a running Docker daemon.

License

MIT