Mergerie
Contents

Configuration (.env)

This page is generated from docs/guide.en.md · Edit this page on GitLab

npx mergerie writes one on its first launch, in ~/.mergerie/.env — next to the data, so it is read back wherever the command is run from: it looks for claude then copilot on the machine (on the PATH, then where the installers put them) and points AGENT_BIN at the one it finds. It is short (a dozen lines), written once, mode 600, never rewritten afterwards, and the command says what it created. npx mergerie demo writes none: it promises to leave nothing behind.

The agent is also set on screen, without a restart — Settings → AI session → Agent binaries: the default line carries the binary, its base arguments, the timeout of one call, and a Test button (one real, short, read-only call whose expected answer is “OK”); the other lines are the alternatives a session can pick, see Several binaries, one default below. What is filled in there wins over the .env. No agent found? A banner says so at the top of the screen, with the path looked for and the install commands, and “Retry” redoes the detection without restarting the server — until then reports are simulated and say so. What the agent is allowed to do is no longer set in the .env: see Secured or yolo in the same sub-tab, and the Security section.

Four backends, and a guarantee level said in plain words. Claude Code and Copilot CLI are proven; Codex CLI and Gemini CLI are written from their documentation, never tried by the maintainer (Settings say “unverified”: the first real run will tell); an unknown CLI is run as is. The backend is detected from what the binary answers to --version, then from its name, and can be chosen in Settings → AI session (or AGENT_BACKEND) when detection gets it wrong. Next to its name, the level of what that backend can promise: proven (the CLI's sandbox was seen blocking a write outside the folder and a network call on this machine — “Test the sandbox”), declared (the CLI can restrict itself — --restricted, --sandbox read-only, --deny-tool — but nothing proved it here: the after-the-fact integrity check is what counts), lightened (none of that: the after-the-fact check is the only net, and every run's journal says so on its first line). No level blocks a CLI; what is never lightened: the forge token out of the clone, the API closed by the local token, the allowlisted environment, the wide-open mode stripped from the arguments. Whenever a read-only run (review, exploration, knowledge update) lands on a backend that denies it writes — Claude, Codex, Gemini, and Copilot when it knows --deny-tool — the instruction asks for the final answer instead of a file the agent could not write.

Two .env files are read at startup, weakest first: ~/.mergerie/.env, then the one in the folder the command is run from (the root of the clone with npm start, the current directory with npx mergerie) — the local override. What the shell exports wins over both. The old names COPILOT_BIN, COPILOT_ARGS, COPILOT_TIMEOUT_MS are still read.

VariableDefaultRole
PORT4319server port
HOST127.0.0.1listening interface; 0.0.0.0 to expose on the network — see the Security section
AGENT_BINcopilotthe AI agent's binary (e.g. claude) — overridden by the on-screen setting when filled (COPILOT_BIN still read)
AGENT_ARGS—args passed BEFORE -p (e.g. --model …) — same (COPILOT_ARGS still read)
COPILOT_DRY_RUN01 = force mock mode (no AI)
AGENT_TIMEOUT_MS900000timeout of an AI call (15 min) — same (COPILOT_TIMEOUT_MS still read)
GITLAB_CA_CERT—path to a CA to pin (self-hosted GitLab) — recommended
GITLAB_INSECURE_TLS01 = skip the TLS check for GitLab only (troubleshooting)
GITHUB_CA_CERT—same for a GitHub Enterprise instance with an internal CA
GITHUB_INSECURE_TLS01 = skip the TLS check for GitHub only (troubleshooting)
JENKINS_CA_CERT—same for an internal Jenkins behind a corporate certificate
JENKINS_INSECURE_TLS01 = skip the TLS check for Jenkins only (troubleshooting)
GIT_CLONE_SSH01 = clone over SSH (your key) instead of HTTPS+token
MERGERIE_DATA_DIRdata/isolated data folder (useful for tests)

The variables the CLI reads and Mergerie does not know — an Ollama behind Claude Code (ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama), a proxy, a key — can also be set on screen: Settings → AI session → “Agent environment variables”, NAME=value per line. They are passed to the agent Mergerie launches only, never to your terminal (your everyday claude keeps its subscription), override the shell, and count on the next agent launch without a restart. This workstation only, never shared; MERGERIE_* is refused.

Several binaries, one default. Settings → AI session → Agent binaries is a list: the default first, marked — the one used by reviews, convergence, free questions and any session that picked nothing —, then the others, as many as you like. Each line says its state (found, not found), tests with a button and edits through the same form (name, binary, arguments, environment variables; timeout and backend under “Advanced”). A profile is complete: it does not complete the default (its variables replace the default's, its empty arguments stay empty). A Claude Code wired to a local Ollama next to your Claude Max, a Copilot to compare. In a session's modal (coding, exploration, out of repository), a “Binary” picker appears as soon as there is one besides the default; the choice holds for every pass of the session — follow-up, answers, approved plan, convergence — and its card shows it. “Use as default” swaps a line with the default: the former default takes its place in the list, sessions that had picked it keep it (an explicit choice stays explicit), and the sandbox proof drops, as with any change of binary. This workstation only, never shared: these are paths of this machine, often secrets — on a teammate's workstation, the card of a shared session says the name of the chosen binary, and rerunning it uses their own default.

Coding sessions write in the clone: in secured mode the CLI's sandbox (once proven) or a command allowlist bounds them, in yolo nothing from the launcher does — see Secured or yolo in the Security section. Explorations, on the other hand, are read-only: the repositories are reset after each pass.