Pi Containerized

Run Pi in a container! This is a template to containerize Pi so you can get work done without worrying about naughty agents. This setup also prevents Pi from modifying .git/, so you can always get back your files.

Design choices:

• A single persistent container runs in the background.
• Your current directory is bind-mounted to /workspace.
• .git is shadowed by a tmpfs mount: reads work, writes are discarded.
• Pi session state and config are stored on a tmpfs at /tmp/pi inside the container and discarded when the container stops
• NPM_CONFIG_CACHE stored in /tmp/npm-cache, prevents Pi from polluting project when it uses e.g. brave search
• Kimi K2.6 model set by default

You can use this repo in two ways:

1. Start a new project — clone or fork this repository, delete README.md, build something new
2. Add to an existing project — copy Containerfile and justfile into your repo

Provider

This setup defaults to OpenRouter. You can edit the justfile to change providers.

Prerequisites

• Podman
• just
• secret-tool (from libsecret; usually pre-installed on GNOME)
• OpenRouter API key

Quick start

1. Store your API keys

secret-tool store --label="OpenRouter API Key" type openrouter
secret-tool store --label="Brave API Key" type brave repo api   # optional

2. Use Pi

just pi

Start using Pi.

3. Update Container

You can use a prompt like this to install dependencies for Pi (or really make any change to this setup):

You are running inside an Alpine linux based container. Edit Containerfile so that you have the necessary base image and dependencies to work on this codebase. Then request the user run `rebuild-pi` to apply the changes.

Commands

justfile does not include a build command by default. Add one (or ask Pi to add one) once the project's build system is known.