garaje

Park your codebases. Let the agent drive.

garaje is a command-line tool for running the pi coding agent against the codebases you actually work on — each one containerized with its own datastores, alongside the agent, in a single Docker Compose project called a garaje. You scaffold a garaje, hand it your repos, and the in-container agent wires each one up for agentic development.

The design goal is portability: your dev environment is declared as data (a manifest + per-codebase recipes), the agent harness is a swappable package, and the same garaje runs locally on Docker today (Kubernetes is on the roadmap).

npm install -g garaje

Requires Docker (Desktop or Engine) on the host. The agent and its tools run in containers; garaje itself is a thin, dependency-light wrapper over docker compose.

Quick start

# 1. Scaffold a new garaje (a git repo that hosts your parked codebases)
garaje init my-workspace
cd my-workspace

# 2. Start it — builds the agent container and brings the project up
garaje up --build

# 3. Drop into the agent
garaje pi

Then, from inside the agent, point it at a codebase and ask it to park it — the agent introspects the repo, writes a recipe.yaml describing how it runs (toolchain, processes, datastores, env), generates the container config, and commits it. From then on that codebase is a first-class, live-reloading, agent-assisted dev target in your garaje.

Stop without losing your work or your credentials:

garaje down        # refuses -v, so the agent's auth + provisioned tokens survive
garaje up
garaje pi -c       # continue your most recent session

Concepts

| Term | What it is | |------|-----------| | garaje | A git repo + Docker Compose project that runs the pi agent next to the codebases it works on. One per developer, or one shared per team. | | bay | A parked codebase inside a garaje (bays/<name>), materialized from the manifest. The garaje commits the manifest, not the code. | | recipe.yaml | A platform-neutral description of how one codebase runs — its toolchain, app processes, backing services, env, and secrets. Lives in the codebase; the agent authors it by introspection. | | @garaje/base | The agent-side substrate — the persona, rules, roles, and skills the in-container agent loads. Pinned declaratively in .pi/settings.json; installed automatically in-container. |

Commands

garaje init <name> [dir]    scaffold a new garaje
garaje up [--build]         build + start the garaje (host-only)
garaje down                 stop it (refuses -v; auth/tokens persist)
garaje pi [-c]              open the pi agent TUI (-c continues the last session)
garaje attach               attach to the running agent
garaje logs                 tail container logs
garaje doctor               health-check the garaje
garaje sync [name]          clone the manifest's codebases into bays/
garaje list                 list parked bays
garaje park [name]          regenerate the compose from the bays' recipes
garaje bay <up|down|logs|ps>  operate a parked bay's services
garaje auth <add|list|remove> provision git / gh / integration credentials
garaje upgrade [--to <v>]   bump the framework + base pins, flag override drift
garaje sessions-index       index the agent's session transcripts

How it works

• Compose split by ownership. A thin top-level docker-compose.yml includes the framework layer (the agent container); parked codebases live in a generated compose.bays.yaml. The agent shapes services by editing recipes, never the compose files it can't reconfigure itself.
• Bind-mounted, live-reloading. The repo is mounted into the containers, so edits the agent makes take effect immediately — no image rebuilds for code changes.
• Least-privilege Docker. The agent reaches Docker only through a default-deny socket proxy, never the raw socket.
• Layered, declarative config. The shared @garaje/base package is pinned and consumed read-only; a garaje customizes by layering local overrides on top — so upgrading the framework is a pin bump, not a merge.

Framework & harness portability

garaje separates the dev environment (yours, committed as data) from the agent harness (a package). Today the harness is pi via @garaje/base; the seam is deliberately thin so a different harness is a different base package, not a rewrite. The runtime is Docker Compose locally, with a Kubernetes driver planned for the cloud — the same recipe, two runtimes.

garaje and @garaje/base are released in lockstep. Upgrade a garaje with garaje upgrade, which bumps the pins and flags any local override that now shadows or orphans a changed base resource.

License

MIT