Pier Onboard

---
name: pier-onboard
description: Set up a repository for pier — inspect the project, write its committed .pier configuration, and update .gitignore for loose local files so pier sessions boot ready to work. Use when asked to set up, onboard, or configure pier for a repo.
---

# Onboard a repository to pier

pier runs coding-agent sessions as micro-VMs on the user's own AWS account.
When a session is created, the repo is checked out on the VM, uncommitted
edits arrive as a patch, and three optional files in a repo-root `.pier/`
directory control the rest:

| File | When it runs / travels | What belongs in it |
|---|---|---|
| `.pier/bake.sh` | Once, during `pier bake`, on a throwaway instance that becomes the repo's AMI | **Toolchains** — language runtimes, package managers |
| `.pier/setup.sh` | Once during `pier bake` (the prebuild), then once per new session, async, after the repo lands | **Repo state** — dependency install, services, migrations, seeds |
| `.pier/include` | List read at create time; matching files ride to the VM | **Ignored files** dev needs — env files, local certs |

Your job: inspect this repo, write the files that apply, protect loose local
files through `.gitignore`, and tell the user what to run next. All three
files are optional — write only what the repo needs.

## Step 1 — inspect the repo

Look at (where present): `package.json` (especially the `packageManager`
field), lockfiles, `go.mod`, `pyproject.toml` / `requirements.txt`,
`Cargo.toml`, `Gemfile`, `Makefile`, `docker-compose*.yml`, the README's
dev-setup section, `.gitignore`, and any existing `.env*` files on disk.
From that, determine:

1. **Toolchains beyond the default image.** The image already ships:
   node 22 + npm, git, gh, make, docker (with compose and buildx), tmux,
   jq, curl, unzip, and headless Chromium (playwright). Do **not**
   reinstall these. Anything else the build needs — pnpm/yarn, python,
   uv, rust, java — goes in `.pier/bake.sh`.
2. **The dev-setup sequence** — the commands a human runs after a fresh
   clone (install deps, start services, migrate, seed). That's
   `.pier/setup.sh`.
3. **Ignored files** that dev needs — usually `.env*`. That's `.pier/include`.
   Non-ignored untracked files travel automatically when creating from HEAD;
   ignored files travel only when listed here. Pier prints which ignored env
   files it is *not* carrying at create time.

## Step 2 — write `.pier/bake.sh` (only if toolchains are needed)

Runs as the `agent` user with passwordless sudo on the bake instance.
**There is no repo checkout yet** — bake predates any session — so nothing
here may reference repo files; pin versions inline. A nonzero exit aborts
the bake. Everything must be non-interactive.

Example for a repo whose `package.json` pins `"packageManager": "pnpm@10.6.5"`:

```bash
#!/usr/bin/env bash
# pier bake hook: runs once on the bake instance (agent user, passwordless
# sudo, NO repo checkout). Toolchains only; repo state goes in .pier/setup.sh.
set -euo pipefail

# corepack ships with node 22 but prompts on TTYs before downloading —
# silence it machine-wide, then prefetch the pinned pnpm.
sudo corepack enable
echo COREPACK_ENABLE_DOWNLOAD_PROMPT=0 | sudo tee -a /etc/environment >/dev/null
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack install -g pnpm@10.6.5
```

For apt installs, use `sudo DEBIAN_FRONTEND=noninteractive apt-get install -y …`.

## Step 3 — write `.pier/setup.sh`

Runs asynchronously in a `setup` tmux window on the session's first boot,
with the repo root as cwd, after the checkout, dirty patch, non-ignored
untracked files, and `.pier/include` extras are all in place. The user's
secrets env (`~/.config/pier/env`) is loaded. Output logs to
`~/.pier-setup.log`; a
nonzero exit shows as `(setup failed)` in `pier ls`, so **let failures
fail** — start with `set -euo pipefail`, don't swallow errors.

**It must be safe to re-run on a warm disk.** `pier bake` runs it once on a
checkout and images the result, and every new session from that image runs
it again, over the dependencies, build caches and volumes the earlier run
left. A claimed pooled session and a woken parked session never re-run it:
their containers and data are already there. Use installs that are incremental when
nothing changed (`pnpm install`, `poetry sync`, `docker compose build`,
`docker compose up -d`), and never fail on "already exists".

Prefer the repo's own entry point (`make install`, `make dev-setup`) over
duplicating its steps. Typical shape:

```bash
#!/usr/bin/env bash
# pier setup: runs async in the session's "setup" tmux window on first
# boot, cwd = repo root. Logs to ~/.pier-setup.log.
set -euo pipefail
pnpm install
docker compose up -d
pnpm db:migrate
```

Everything must be non-interactive — no prompts, no `sudo` that asks, no
watch-mode/foreground processes. Run services with `docker compose up -d`
where possible. A server the script starts in the background
(`cmd >log 2>&1 &`) keeps running after the setup window closes.

While you're in the compose file, check what makes it slow to come up. A
one-shot job that other services wait on (`service_completed_successfully`)
runs on every `up`, so it must talk to the services already running, not
boot its own (a CLI without its server URL often starts a throwaway local
server per command).

## Step 4 — write `.pier/include` (only if ignored files are needed)

One path or glob per line, relative to the repo root. `*`, `?`, `[]` match
within a path segment — **no `**`**. A directory line carries its whole
subtree. `#` starts a comment. Listed files travel exactly as they sit on
disk and win over the checkout. A file symlink matched directly by a line or
glob is dereferenced into a regular file at the same repository path;
directory symlinks are not followed. Example:

```
# env files docker compose and the apps read
.env
apps/*/.env.local
```

Only list what a dev session genuinely needs — everything listed leaves
the laptop for the VM.

Ensure every loose local file or path added here has a repository-root or
nested `.gitignore` rule so it cannot be committed accidentally. Add only
missing rules and preserve all existing content. **Never ignore `.pier/`**:
the Pier config directory contains project configuration and is meant to be
committed (but a new, not-yet-committed `.pier/setup.sh` still travels).

## Step 5 — finish

- The `.pier/` files and any `.gitignore` updates are meant to be committed.
  Pier runs both scripts with bash, so the exec bit is optional.
- Tell the user to run `pier bake` in the repo: it installs the bake hook's
  toolchains and prebuilds the repo by running `.pier/setup.sh` once, so
  sessions start with dependencies already installed. Re-run it after
  changing `.pier/bake.sh`, or when dependencies have drifted enough that
  session setup gets slow. Then create a session and
  watch `pier ls` — `(setup running)` should clear; if it shows
  `(setup failed)`, attach and read `~/.pier-setup.log`.
- If `.pier/setup.sh` is heavy (long installs, docker pulls, migrations),
  mention pooled sessions: once the repo is baked, pier keeps parked,
  setup-complete sessions to claim (one by default; `pier pool set <n>` or the
  app's Repos tab changes it), so new sessions skip the wait (~$3-4/mo each,
  disk only). Changing `.pier/setup.sh` later is safe — pooled sessions
  notice and recycle on the next claim or refill.