Getting Started

This guide takes you from nothing to a running vignoble with a conductor.

A six-stop sketched journey from a Pinard installation crate through credentials, estate creation, repository registration, daemon startup, and an open conductor control room. 1 2 3 4 5 6 Install Credentials Create vignoble Register vigne Start daemon Launch conductor
Your first vignoble, in six stops. The illustration is a progress map; the commands below remain the source of truth.
  1. 1Install Pinard from a release bundle or source.
  2. 2Configure GitLab and NATS credentials.
  3. 3Scaffold the vignoble with aoc init.
  4. 4Register each repository as a vigne.
  5. 5Start the always-on daemon.
  6. 6Optionally enter the conductor control room.

Install

Pinard ships two ways.

A release is a single self-extracting .run archive (Linux/glibc x64). It bundles the aoc binary, the launcher, the Pi extensions, and a vendored Node + Pi runtime — so the host needs only the thin CLIs tmux git glab fzf, no Node/npm.

./pinard-linux-x64.run          # installs to ~/.pinard, symlinks aoc/pinard into ~/.local/bin

From source

cd pinard/cmd/aoc && make install   # builds + installs aoc to ~/.local/bin
./install                            # sets up config templates, permissions, pre-commit hook

Runtime requirements: ./install enforces Node ≥ 22.19.0 and Pi ≥ 0.80.6. If nvm is available it activates the pinned Node (22 LTS) from .nvmrc automatically; otherwise install Node 22 manually before running ./install. Node 22 LTS ships native prebuilts for better-sqlite3, so no C++ compiler is needed on the host.

Set PINARD_NODE=/path/to/node to override which node binary is used when the nvm default is too old; the launcher and daemon both respect this variable.

aoc is a static Go binary with zero runtime dependencies.

The engram CLI is installed (or upgraded/downgraded) to the same version the cluster runs — pinned in .engram-version at the repo root. This keeps the local and cloud engram in lockstep; a version drift can cause cloud sync to fail due to mutation/chunk format mismatches. Re-running ./install after a cluster upgrade will update your local engram CLI automatically.

Credentials

Pinard authenticates to GitLab (as a dedicated service account) and to NATS. All fields must be set explicitly — there are no built-in defaults. Copy the bundled template:

cp credentials.example.yaml ~/.config/pinard/credentials.yaml
# then fill in your values

Minimal ~/.config/pinard/credentials.yaml:

gitlab:
  host: gitlab.example.com           # GitLab API hostname (no scheme)
  user: your-bot-user                # GitLab username of the service account
  token_env: PINARD_GITLAB_TOKEN     # env var holding the PAT
  ssh_key: ~/.ssh/pinard_id_ed25519
  git_name: Pinard
  git_email: bot@example.com

nats:
  url: wss://nats.example.com        # NATS JetStream WebSocket URL (required)
  user: your-nats-user
  password_env: PINARD_NATS_PASSWORD

Then export the secrets in your shell (or put them in ~/.config/pinard/env, which the daemon reads on start):

export PINARD_GITLAB_TOKEN="glpat-xxxxx"
export PINARD_NATS_PASSWORD="xxxxx"

See Configuration for the full schema including optional blocks (engram:, webterm:, and the Buddy Capsule PINARD_MNEMOSYNE_URL).

Create a vignoble

aoc init scaffolds a complete vignoble directory and starts the daemon:

aoc init myproject --gitlab-host gitlab.com --gitlab-group mygroup
cd ~/vignoble-myproject

This creates vignes.yaml, schedules.yaml, PINARD.md, the .state/, logs/, changes/, and parcelles/ directories, and the conductor permission files. It has no systemd dependency — the daemon self-supervises.

Register a vigne

Add each repository you want to orchestrate:

aoc add vigne my-api --path ~/my-api --repo mygroup/my-api

This appends an entry to vignes.yaml. Repeat for every repo. (Add --auto-merge only if you want that vigne’s MRs merged automatically — it’s off by default; see Configuration.)

Run the daemon

The daemon is the always-on engine (MR/issue/schedule watchers, auto-spawn, dispatch):

aoc daemon start      # self-daemonizes, logs to logs/aoc-daemon.log, PID in .state/daemon.pid
aoc daemon status     # check it's alive

aoc daemon start/stop/restart/status manage the background process. It hot-reloads itself when the aoc binary, vignes.yaml, or schedules.yaml change.

Launch the conductor

The conductor (régisseur) is an interactive Pi session that receives events, spawns agents, and lets you steer work conversationally:

cd ~/vignoble-myproject
pinard

Run pinard from anywhere (with no vignoble) to pick and attach to a running session via fzf. The conductor is optional — the daemon does the mechanical work on its own — but it gives you the LLM-powered control room.

Next steps