# Shared hardening for the sidecar containers (harness/inference-gw). The runner # is the trusted orchestrator and deliberately not hardened this way. x-hardened: &hardened read_only: true tmpfs: - /tmp security_opt: - no-new-privileges:true cap_drop: - ALL services: runner: build: context: . dockerfile: Dockerfile.runner # SCRIPT_DIR is set (to an absolute path) by ./opilot, which mounts the repo # at its real host path so the paths the agent computes resolve identically # inside the container. When unset — e.g. a bare `docker compose run runner …` # for tests — it falls back to mounting the current project at a fixed path, # so no SCRIPT_DIR=… prefix is needed. Each repo's standalone clone lives under # .opilot/repos/, covered by this single mount. # Run as the host user (exported by ./opilot) so files written into the # bind-mounted .opilot/ are owned by you, not root. Defaults to root when # unset, e.g. a bare `docker compose run runner …` for tests. user: "${OPILOT_UID:-0}:${OPILOT_GID:-0}" volumes: - ${SCRIPT_DIR:-.}:${SCRIPT_DIR:-/opilot} environment: # Non-root needs a writable HOME for bundler/git config scratch. - HOME=/tmp - GITHUB_CONTRIBUTOR_TOKEN=${GITHUB_CONTRIBUTOR_TOKEN:-} - HARNESS_URL=http://harness:47291 # `usage` reads OpenRouter's account/key balance through inference-gw, the same # non-secret handshake pi uses for inference — never the real key. - OPILOT_INFERENCE_GW_URL=http://inference-gw:47292 - OPILOT_GW_TOKEN=${OPILOT_GW_TOKEN:-} # Reporting only — the runner never calls the upstream directly. `usage` # names the endpoint it is (or is not) reading spend from. - OPILOT_INFERENCE_URL - GIT_AUTHOR_NAME - GIT_AUTHOR_EMAIL - GIT_COMMITTER_NAME - GIT_COMMITTER_EMAIL - OPENPROJECT_URL=${OPENPROJECT_URL} - OPENPROJECT_TOKEN=${OPENPROJECT_TOKEN} - OPILOT_ALLOWED_OP_USER_IDS=${OPILOT_ALLOWED_OP_USER_IDS:-} - OPILOT_ALLOWED_GH_USERS=${OPILOT_ALLOWED_GH_USERS:-} # The op_query tool grant. Bare form: unset must mean # "off", not "blank" — Context#op_mcp? reads it the same way # OPILOT_TRACK_UPSTREAM_PRS is read. - OPILOT_OP_MCP # The gh_query tool grant. Bare form and OFF unless set, unlike # OPILOT_OP_MCP: it needs a GitHub read token, so ./opilot exports it # only when one is configured. - OPILOT_GH_MCP # Where the runner reaches mcp-gw for the startup tool-list check # (Helpers#report_mcp_status). Bare form, exported by ./opilot only # when the flag above and the harness are both needed — unset here means # "not running through ./opilot", which the check reports rather than # guessing at a URL. - OPILOT_MCP_GW_URL # The optional knobs, passed WITHOUT a default (`- VAR`, not # `- VAR=${VAR:-}`): Compose resolves the bare form from .env too, but an # explicit `${VAR:-}` would hand the container an empty string, and an # empty string beats the default in every `ENV.fetch(name, default)` # reader (Context, Harness). Unset must mean absent, not blank. - OPILOT_MODEL_HEAVY - OPILOT_MODEL_LIGHT - OPILOT_CI_MAX_ATTEMPTS - OPILOT_CI_IGNORE_CHECKS # Read by server.js to bound a run, and by Harness::READ_TIMEOUT to stay # the outer bound over it — so both containers need them. - OPILOT_PI_IDLE_TIMEOUT_MIN - OPILOT_PI_MAX_RUN_MIN - OPILOT_TRACK_UPSTREAM_PRS # The Matrix chat interface (Matrix::Agent). Bare form: unset = off. - MATRIX_HOMESERVER_URL - MATRIX_ACCESS_TOKEN - MATRIX_ROOM_ID - OPILOT_ALLOWED_MATRIX_USERS - OPILOT_PD_PARENT_TYPE - OPILOT_PD_CHILD_TYPE - OPILOT_PD_IMPLEMENTING_STATUS - OPILOT_PD_IMPLEMENTED_STATUS # `./opilot appsignal`. The RUNNER reads AppSignal, not the harness — the # model only ever sees the cached incident file. A personal API token, # because the request payload is reachable no other way (see # Clients::AppSignal). - APPSIGNAL_API_TOKEN - APPSIGNAL_APP_ID - OPILOT_APPSIGNAL_PROJECT # Optional: seeds the openproject clone from a local checkout (bin/repos). - OP_REPO_PATH working_dir: ${SCRIPT_DIR:-/opilot} stdin_open: true tty: true networks: - internal - egress # The harness container is deliberately not published on the host and sits on # an internal-only network with NO default route: server.js is # unauthenticated, so its only client must be the runner, and work-package # text is untrusted, so a prompt injection must have nowhere to send anything. # # inference-gw is its ONLY egress, reachable over the internal network, and that # gateway forwards to one pinned upstream on an allowlisted set of paths — # plus mcp-gw when OPILOT_OP_MCP is set, reached the same way and # allowlisted on the JSON-RPC body rather than the path, since every mcp-gw # call is the same POST /mcp. There is deliberately no general-purpose proxy # beside them: a tinyproxy sidecar used to straddle internal and egress for # Claude Code's WebFetch, but pi ships no fetch tool (bash is confined to # read-only git), so it # carried zero traffic and served only as a bridge out of the contained # network. Removing it made egress strictly zero-except-inference-gw (plus mcp-gw, # when opted into). Restoring any outbound path is a deliberate decision, # not a default. harness: build: context: . dockerfile: Dockerfile.harness # Run as the host user (exported by ./opilot) so files pi writes into the # bind-mounted .opilot/pi-agent and .opilot/pi-sessions are owned by — # and persist for — you. The image's baked node user is uid 1000; on a # host whose user isn't 1000 that node uid can't write host-owned dirs, so # nothing would persist. Defaults to 1000 (the node user) when unset, e.g. # a bare `docker compose run`. user: "${OPILOT_UID:-1000}:${OPILOT_GID:-1000}" # Run the CLI in /repos (the parent of every repo's worktree) so pi sees # them all at /repos/. --no-context-files (server.js) stops pi from # auto-loading a repo's CLAUDE.md/AGENTS.md on its own — the prompts tell # it to read each target repo's directly instead (see the --no-context-files # comment in server.js for why). working_dir: /repos volumes: # pi's config dir (settings.json/models.json seeded by server.js, # auth.json, model catalogs) — writable so first boot can seed it. - ${SCRIPT_DIR:-.}/.opilot/pi-agent:/pi-agent # Session transcripts, keyed by --session — writable, and now on a # host mount so a session survives the container being recreated. - ${SCRIPT_DIR:-.}/.opilot/pi-sessions:/sessions # Every repo's standalone clone, at /repos/. pi reads/edits files # here and browses git history (read-only) — each clone carries its own .git. - ${SCRIPT_DIR:-.}/.opilot/repos:/repos # Read-only: pi only reads item/plan files from here; the runner is the # sole writer of .opilot state. Defense-in-depth beyond the write-guard. - ${SCRIPT_DIR:-.}/.opilot:/state:ro environment: - PI_CODING_AGENT_DIR=/pi-agent - PI_CODING_AGENT_SESSION_DIR=/sessions # When running as the host uid, /home/node (owned by the baked node user) and # an absent passwd entry would otherwise break os.homedir(); point HOME at the # tmpfs so stray cache writes land there. Config/sessions still persist via # the two mounts above, which are host-owned, writable bind mounts. - HOME=/tmp - FORCE_COLOR=1 - GIT_DISCOVERY_ACROSS_FILESYSTEM=1 # The real OpenRouter key never reaches this container: pi-models.json # routes the openrouter provider through inference-gw (which holds the real # key) and authenticates with this non-secret handshake token. The same # token authenticates pi's MCP client to mcp-gw. - OPILOT_GW_TOKEN=${OPILOT_GW_TOKEN:-} # Bare form, deliberately: server.js registers no MCP server when this is # unset, the second half of the feature flag beside the runner's grant. # ./opilot exports it only when both the harness and the flag are needed. - OPILOT_MCP_GW_URL - PI_OFFLINE=1 # server.js reads the model slugs to decide whether to copy the # openrouter provider config from git or generate one for a self-hosted # upstream — the provider prefix on OPILOT_MODEL_HEAVY is the only signal. # OPILOT_MODEL_API picks the wire protocol (default openai-completions); # it is the axis the auth header does not cover. - OPILOT_MODEL_HEAVY - OPILOT_MODEL_LIGHT - OPILOT_MODEL_API - OPILOT_MODEL_CONTEXT_WINDOW # Whether a self-hosted model can see pictures. Only read for a generated # provider config: pi's own catalog answers this for openrouter. - OPILOT_MODEL_VISION # Optional run bounds, in minutes (server.js). Bare form, so unset means # "use the default" — server.js falls back on anything non-numeric anyway. - OPILOT_PI_IDLE_TIMEOUT_MIN - OPILOT_PI_MAX_RUN_MIN networks: - internal # Resource limits are the fourth defense-in-depth layer, beside compute # isolation, the filesystem guard (pi-guards.ts) and the network controls # above. They also bound a denial-of-service the queue in server.js makes # worse: one run that eats the box blocks every other tick, because the # harness serves one call at a time. # # These defaults are deliberately GENEROUS and unmeasured. A mem_limit set # too low produces OOM-killed runs that look exactly like the idle timeout # firing, which is the most expensive way to get this wrong. Measure a real # multi-repo `wp build` with `docker stats`, then tighten to roughly twice # the observed peak via the env vars below. mem_limit: ${OPILOT_HARNESS_MEM:-4g} cpus: ${OPILOT_HARNESS_CPUS:-2} pids_limit: 512 <<: *hardened healthcheck: test: ["CMD", "node", "-e", "require('http').get('http://localhost:47291/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"] interval: 2s timeout: 5s retries: 15 # Inference gateway — the harness's only route to a model, and CONTAINMENT is # its load-bearing job rather than authentication (the name predates that). # It pins one upstream and its resolved address at boot, allows only the # inference paths, and attaches the real key — which therefore never lives # alongside untrusted work-package content. pi points its provider baseUrl # here and authenticates with the fixed gateway token. A keyless self-hosted # upstream still goes through it: it is never an open proxy, whether or not # there is a secret to hold. inference-gw: build: context: . dockerfile: Dockerfile.inference-gw environment: # Which upstream this gateway forwards to, and how it presents the key. # The defaults live in inference-gw.js and point at OpenRouter. - OPILOT_INFERENCE_URL - OPILOT_INFERENCE_KEY - OPILOT_INFERENCE_AUTH # Fixed handshake value (not a secret); must match the value # pi-models.json resolves $OPILOT_GW_TOKEN to in the harness container. # opilot exports this (the single source for the value). - OPILOT_GW_TOKEN networks: - internal - egress <<: *hardened healthcheck: test: ["CMD", "node", "-e", "require('http').get('http://localhost:47292/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"] interval: 2s timeout: 5s retries: 15 # The OpenProject MCP gateway — the harness's only route to the # OpenProject MCP server, on when OPILOT_OP_MCP is set. Same containment # shape as inference-gw: a fixed upstream (OPENPROJECT_URL), a pinned address, and # a swap of the handshake token for the real credential — but the allowlist # here is on the JSON-RPC BODY (mcp-gw.js parses it), not the path, because # every call is the same POST /mcp. Six of the instance's MCP tools WRITE to # OpenProject; this is what keeps them unreachable from the harness even # though the OPENPROJECT_TOKEN handed to it can write. mcp-gw: build: context: . dockerfile: Dockerfile.mcp-gw environment: - OPENPROJECT_URL - OPENPROJECT_TOKEN # The GitHub route. OPILOT_GH_MCP is the switch (off by default — GitHub # is a third party, so reaching it is an explicit opt-in). The credential # is opilot's one GitHub identity: it can write, but no write is reachable # through the pinned /readonly path and the operation allowlist, and # this container already holds a write-capable OPENPROJECT_TOKEN on the # same footing. - OPILOT_GH_MCP - GITHUB_CONTRIBUTOR_TOKEN # Optional; defaults to GitHub's own hosted MCP server on its readonly # path. Points at a locally run `github-mcp-server http` instead. - OPILOT_GH_MCP_URL # Fixed handshake value (not a secret), the same one inference-gw and pi-mcp.ts use. - OPILOT_GW_TOKEN networks: - internal - egress <<: *hardened healthcheck: test: ["CMD", "node", "-e", "require('http').get('http://localhost:47293/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"] interval: 2s timeout: 5s retries: 15 networks: # No route to the outside world. The harness holds untrusted work-package # text and sits here alone with the runner, inference-gw, and (when OPILOT_OP_MCP # is set) mcp-gw, so its only reachable outbound paths are those two gateways — # each pins one upstream and allows only its own narrow allowlist. Verify # with `docker compose exec harness cat /proc/net/route`: there must be no # row with destination 00000000. internal: internal: true egress: