◐banyan

Configuration

The YAML config schema — projects, repos, run, env management.

Banyan reads ~/.config/banyan/config.yaml (or $BANYAN_CONFIG if set). One file, all projects.

Minimal example

version: 1
projects:
  - name: myproject
    repos:
      - name: front
        path: ~/Dev/myproject/front
        baseBranch: develop
        run:
          command: npm run dev
          port: 3000
          portEnv: PORT

Full example

version: 1
projects:
  - name: myproject
    repos:
      - name: front
        path: ~/Dev/myproject/front
        baseBranch: develop
        copyOnWorktree:
          - .env.local
        loadEnvFiles:
          - .env.local
        run:
          command: npm run dev
          port: 3000
          portEnv: PORT
          setup: npm install
          env:
            REACT_APP_API_URL: http://localhost:{{back.port}}
 
      - name: back
        path: ~/Dev/myproject/back
        baseBranch: develop
        copyOnWorktree:
          - .env.local
        loadEnvFiles:
          - .env.local
        run:
          command: ./gradlew bootRun
          port: 8080
          portEnv: SERVER_PORT
          stopCommand: ./gradlew --stop
          composePorts:
            DB_PORT: mysql-dev:3306
 
      - name: infra
        type: compose
        path: ~/Dev/myproject/back
        composeFile: docker-compose.dev.yml

Repo fields

FieldDescription
nameRepo identifier (used in tmux pane titles, branch names)
pathMain checkout location. Stored as ~/... for portability.
techTech profile id picked at wizard time (node, spring-boot, android, django, custom). Drives the suggested defaults for run.command / port / portEnv.
baseBranchDefault base for merge/rebase (else detected from origin/HEAD)
mergeStrategysquash / merge / rebase. Default: squash
copyOnWorktreeFiles to copy from main checkout → fresh worktree on bn wt. Relative paths only, no ...
loadEnvFiles.env-style files to parse and inject as env vars at run-time
run.commandShell command for bn start to spawn
run.portCanonical port. Banyan probes from port + 1 to allocate per feature.
run.portEnvEnv var your framework reads (PORT, SERVER_PORT, …)
run.setupOne-shot before each run (npm install, bundle install)
run.stopCommandClean-shutdown command, run by bn stop / bn cleanup
run.envExtra env vars. Supports {{<repo>.port}} cross-repo templating
run.composePorts<env-var>: <service>:<containerPort> — inject host port of a compose service
run.presetsNamed alternative commands. Switch via activePreset
typegit (default) or compose
composeFileFor type: compose only — path to docker-compose.yml

Top-level llm: block

version: 1
llm:
  openrouterApiKey: sk-or-v1-…
projects:
  - …

Used by bn wt -p "<prompt>" to auto-name the branch from the prompt via OpenRouter. Free models (e.g. x-ai/grok-4-fast:free) work fine. The key can also come from the OPENROUTER_API_KEY env var, which takes precedence over the config file. Skip the llm: block entirely if you always pass an explicit feature name on bn wt.

Editing the config

Two ways:

  1. Edit ~/.config/banyan/config.yaml directly. YAML, comments preserved across reloads.
  2. Via the dashboard Config tab. Edits go through a comment-preserving writer. The Config tab also exposes the OpenRouter key (masked) and per-repo run command presets.

copyOnWorktree + loadEnvFiles

Most stacks depend on at least one gitignored file (.env, local.properties, application-local.yml). On bn wt, banyan copies declared files into the fresh worktree. On bn start, it parses .env-style files and prepends each KEY=value to the run command's env.

Banyan's dynamic values override file values:

  1. loadEnvFiles content (lowest)
  2. allocated port + composePorts
  3. declared run.env (highest)

So a .env.local shipping SERVER_PORT=8080 is overridden by banyan's allocated port for parallel features.

Previous

Concepts

Next

Commands

On this page