Configuration

Overview

co:op reads its settings from environment variables, from ~/.config/coop/coop.conf, and from the committed .agent/project.yaml. The website guide covers the settings you're most likely to change.

Environment variables

Set these in your shell or in coop.conf. For settings that turn a feature on or off, use 1/true/yes/on or 0/false/no/off. Letter case does not matter. co:op rejects any other value.

Box and runtime

Choose one of these values for COOP_EGRESS:

• open allows full outbound traffic. This is the default.
• filtered allows the AI provider and domains you have approved.
• none disables the box's network (--network none). The box cannot send the repo, secrets or credentials over the network. Installs and model API calls stop working too, so you must choose this setting explicitly.

An --egress flag overrides COOP_EGRESS. A project's saved coop approve decision also overrides it. COOP_EGRESS itself overrides box.egress in .agent/project.yaml.

The resource and privilege limits (COOP_PIDS, COOP_MEMORY, COOP_CPUS and COOP_NO_NEW_PRIVILEGES) apply on Docker. co:op currently skips them with Apple's container CLI because that runtime works differently.

On Docker, co:op also removes all Linux capabilities (--cap-drop ALL); agent workloads do not need them. Even if a repo's .agent/Dockerfile sets USER root, the container process does not get powers such as CAP_DAC_OVERRIDE, CAP_NET_RAW or CAP_MKNOD.

Agents and config

By default, COOP_CONSULT_TIMEOUT lets each peer take as long as it needs, subject to the calling attempt's limits on tool use and total duration. Set a whole number of seconds (max 86400) to add a timeout. If a peer does not answer in time, co:op skips it and the lead uses the replies that arrived.

A timeout cannot tell a slow answer from a stalled peer. If it interrupts a peer that was still working, that answer is lost and needs a retry.

Forks and loop

You configure loop behavior in .agent/loop.yaml. See the loop for the whole file.

The --preflight flag turns on the same cleanup for one invocation.

Command-valued settings

co:op splits COOP_GATE, COOP_RUN_ARGS and the COOP_<AGENT>_CMD overrides into a list of command arguments (argv). Single and double quotes group text into one argument, and \ escapes a character. co:op does not run these settings through a shell, so it does not expand wildcard paths or $VAR values.

For example, COOP_GATE='bash -lc "make check && make lint"' produces three arguments, not five. A bare &&, | or $VAR is passed literally. Wrap commands that need those shell features in bash -lc "…". COOP_REVIEW_CMD is the exception: co:op runs it through sh -c.

coop.conf

~/.config/coop/coop.conf takes the same settings as KEY=VALUE lines. The environment wins over the file.

The default file is optional. If you set COOP_CONF, the chosen file must exist. If co:op cannot read it, the error names the path. If a setting is malformed, duplicated, retired or unknown, the error names the path and line. An environment override does not let a broken file pass.

COOP_CONF, NO_COLOR, COOP_ACP_WARM and COOP_SPINNER are process-environment controls, so you can't set them inside coop.conf.

Optional provider usage reports use a separate host-only ~/.config/coop/usage-reports.json. Their API spend is never added to local usage estimates. Reporting keys belong in host environment variables, not coop.conf, project files or agents/env.

Project settings: .agent/project.yaml

.agent/project.yaml is the committed per-project config.

Explicit COOP_* settings in your environment or coop.conf override box: and gate:. Because the project settings file is committed and read on the host, it may tighten security restrictions but cannot relax them on its own:

• egress can pin filtered or offline.
• open is a request that a human approves with coop approve.
• no_new_privileges isn't settable here.

Path-routed context

Use coop context to give an agent the committed docs relevant to the files it is working on. This avoids loading every rule and knowledge-base note for a small change. co:op always includes the complete AGENTS.md/CLAUDE.md, then adds documents whose configured path patterns match.

# .agent/project.yaml
context:
  routes:
    - paths: [portal/**, "**/*.ex"]   # * within a segment, ** across segments
      include: [.agent/kb/portal.md]  # repo-relative docs to add when a path matches

coop context --changed            # scope = the paths git reports changed
coop context --task <id>          # scope = a task's declared `paths:` frontmatter
coop context portal/lib/user.ex   # scope = explicit repo-relative paths
coop context --changed --json     # same, as data (files + the route that selected each)
coop context --changed --rendered # the compiled content itself, canonical first

co:op chooses paths from your arguments, Git's changed files, the task's declared paths or the current subproject. It never guesses them from a prompt. It reports an error if a route includes a missing document or a path outside the repo. coop context always keeps the main instructions complete; it does not summarize or truncate them.

Routes come from the committed project.yaml. A fork therefore uses its parent's routes, but matches them against paths in the fork's own tree.

Exit codes

Commands use these exit codes so CI and scripts can check the result without parsing messages.

If final verification is enabled and fails, coop loop keeps the completed work and exits with a nonzero code. It uses 1 unless the outcome is blocked work only, which takes precedence. An intentional --max-tasks N pause exits successfully but leaves final review pending. See the loop's exit codes.

JSON output

Most commands that change state report success or failure through exit codes rather than --json. Read-only commands offer JSON when other tools need the current state. The two main views are:

• coop tasks watch --json is the canonical project task and activity snapshot.
• coop fork ls --json discovers workspace URLs plus fork status.

coop context, the coop net views and coop sessions doctor also accept --json. coop net export always writes JSON. Use exit codes to check commands that change state, and the host's JSON views to read the current combined state.