Storage, containers, and CI

Standalone Evolver identity, assets, events, mailbox, memory, and logs have separate persistence responsibilities. Define the layout before deploying the same runtime contract to services, containers, or CI. Desktop manages its own internal paths.

Choose persistence by data type

See Asset paths for precedence and directories. Sharing a node ID does not justify sharing writable databases or asset directories.

Configure the startup environment

Supported entry points select environment files through EVOLVER_ENV_FILE or their --env-file option. The loader overrides matching inherited environment values. Reconcile service-manager configuration, arguments, and files, then restart after changes.

Use evolver doctor to inspect sources and connectivity without dumping the process environment. Images contain programs and nonsecret dependencies; inject credentials at runtime. Do not bake identity and assets into public image layers.

Example: bounded CI diagnostics

This is a POSIX runner fragment. The CI platform supplies independent RUNNER_TEMP, Node.js, Git, Evolver, and any required protected credentials:

export EVOLVER_HOME="$RUNNER_TEMP/evolver-home"
export EVOLVER_TASK_RECEIVER=0
export EVOLVER_ATP_AUTOBUY=off
export EVOLVER_ATP_AUTODELIVER=off
evolver doctor
evolver cycle capabilities --json

These are environment and capability diagnostics, without evolution task execution or publishing. Execution jobs separately define repositories, material, runners, validation, and timeouts; ordinary CI must not start an unbounded loop. Inspect diagnostic reports for sensitive paths before uploading.

Example: container diagnostics and GitHub Actions

Save this Dockerfile in a separate example directory. It installs Node.js, Git, and Evolver and runs as a non-root account. The default command diagnoses the environment without starting Proxy, task intake, or a loop.

FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN npm install --global @evomap/evolver \
    && mkdir -p /workspace /home/node/.evomap \
    && chown -R node:node /workspace /home/node/.evomap
ENV EVOLVER_HOME=/home/node/.evomap \
    EVOMAP_HOME=/home/node/.evomap \
    EVOLVER_TASK_RECEIVER=0 \
    EVOLVER_ATP_AUTOBUY=off \
    EVOLVER_ATP_AUTODELIVER=off
USER node
WORKDIR /workspace
VOLUME ["/home/node/.evomap"]
CMD ["evolver", "doctor"]

Use the example directory as build context and mount only an authorized, nonsensitive example project. These commands use a POSIX shell; in PowerShell replace source=$PWD with the actual absolute path.

docker build -t evolver-tools .
docker volume create evolver-example-home
docker run --rm \
  --mount type=volume,source=evolver-example-home,target=/home/node/.evomap \
  --mount "type=bind,source=$PWD,target=/workspace,readonly" \
  evolver-tools
docker run --rm \
  --mount type=volume,source=evolver-example-home,target=/home/node/.evomap \
  --mount "type=bind,source=$PWD,target=/workspace,readonly" \
  evolver-tools evolver cycle capabilities --json

The containers use one volume sequentially; inspect doctor and capabilities separately. Independent instances need separate volumes, and two resident writers must not share this one. Read-only source is sufficient for these diagnostics. Repairs need a separately authorized writable workspace, rather than simply removing the read-only restriction and running arbitrary tasks.

Do not put node secrets in the image. Networked instances obtain credentials through the platform secret store or a read-only environment-file mount, never a Dockerfile COPY. For volume permissions, check runtime UID, directory ownership, and mount point rather than making directories globally writable.

Save the following as .github/workflows/evolver-diagnostics.yml and run it through workflow_dispatch:

name: Evolver diagnostics
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  diagnose:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    env:
      EVOLVER_HOME: ${{ runner.temp }}/evolver-${{ github.run_id }}-${{ github.run_attempt }}
      EVOMAP_HOME: ${{ runner.temp }}/evolver-${{ github.run_id }}-${{ github.run_attempt }}
      EVOLVER_TASK_RECEIVER: "0"
      EVOLVER_ATP_AUTOBUY: "off"
      EVOLVER_ATP_AUTODELIVER: "off"
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - name: Install Evolver
        run: npm install --global @evomap/evolver
      - name: Inspect the isolated runtime
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "$EVOLVER_HOME"
          git status --short --branch
          evolver doctor
          evolver cycle capabilities --json

Each run has an isolated runtime directory and performs local diagnostics and capability inspection only. It does not evolve, claim tasks, or publish. npm installation accesses the package registry; passing diagnostics does not execute a business task. Preserve doctor failures and repair configuration before rerunning, without hiding failures through continue-on-error.

For repeatable delivery, replace global installation with a repository-managed local dependency at an approved exact version, commit package.json and its dependency lockfile, install with npm ci, and invoke the installed node_modules/.bin/evolver. Global npm installation does not consume the project lockfile. For containers, copy those dependency manifests into a separate tool directory, run npm ci there, and use its local executable. Pin the base image and Actions to reviewed immutable digests or commit SHAs. Resolve and review these inputs before running; the diagnostic examples above use registry and tag resolution and do not provide a reproducible dependency graph.

For business CI, separately supply project material, an executor, validation commands, and artifact checks using repository delivery standards. Dependency caching must not include the whole Evolver home. Export credential-free archives when assets need preservation. The next section covers container persistence and restart checks.

Containers and restart acceptance

1. Use a nonprivileged runtime user and a separate writable data mount, with minimum required source and secret access.
2. Create or import permitted test assets and record IDs and counts.
3. Stop writers and restart the container; reconcile node, assets, references, and unfinished queue items.
4. Give a second instance separate directories and ensure it does not consume the same queue twice.
5. Verify recovered content rather than merely confirming a volume mount.

The runtime user needs access to its own persistence directories. Do not solve permissions by sharing unrestricted directories across instances. See Containers and CI for deployment detail and Task queues for resident startup and shutdown.