Secrets and environment setup

Check and synchronize contract-defined environment files, with explicit secret ownership and rotation.

The root .env is the operator-owned local source of runtime values. setup_secrets.sh delegates to scripts/environment_config.py, which reads config/environment-contract.yaml and synchronizes each service’s generated environment view.

Reviewed against local working-tree source, including uncommitted changes, on October 3, 2026. Check the contract in your selected revision before applying these instructions. Existing service views are rewritten from the root values and service templates during synchronization. Edit the root source first; service-only edits can be replaced.

Inspect before synchronizing

From the repository root:

# Read-only check for missing values, duplicate declarations,
# generated-view drift, and file permissions.
./setup_secrets.sh --check

# Validate tracked profile and source/template coverage.
make env-check

A fresh checkout may need root configuration before the local check succeeds. Populate operator-supplied URLs and credentials for the services you intend to use. The checker does not establish network reachability or successful application authentication.

Synchronize service views

After reviewing the root values:

./setup_secrets.sh

The default sync mode preserves populated repository-generated secrets, fills missing or placeholder generated secrets, derives declared values, and reconciles service files against their templates. It sets generated files to mode 0600.

The script may prompt when creating a missing service file. It does not ask before rewriting an existing generated view. Output reports setup status and errors rather than printing generated secret values.

Declared environment files

The inspected contract declares these targets:

File	Role
.env	Operator-owned root source.
app/api/.env	Express API view.
app/web/frontend/.env	Frontend view.
src/.env	Python core view.
app/Artemis Agentic Memory Layer/.env	Obsidian-backed memory-layer view.
services/mcp/artemis-memory/.env	Governed memory MCP view.
services/prove/.env	Provenance service view.

Use the checked-out contract for the authoritative list. Generating a file does not mean a service loads it automatically: the launch command, working directory, or container configuration must load or pass the values its consumer expects.

Secret ownership and rotation

The inspected contract lists MCP_API_KEY, FASTAPI_API_KEY, ARTEMIS_API_KEY_DEFAULT, and GRAFANA_PASSWORD as generated secrets. Database credentials, service URLs, and other operator-owned values must come from their actual owners.

Intentional rotation uses:

./setup_secrets.sh --regenerate

This rotates repository-generated secrets and synchronizes service views. Coordinate dependent clients and running services before using it.

The optional --only KEY ... mode fills missing or blank selected allowed generated secrets without synchronizing service views; --only KEY ... --check checks those selections. It cannot be combined with --regenerate. The current contract marks REDIS_PASSWORD and QDRANT_API_KEY as operator credentials, so they must not be treated as auto-generated setup values.

Authentication belongs to each service

Surface	Credential contract
FastAPI dashboard, app/api/main.py	Reads FASTAPI_API_KEY, falling back to MCP_API_KEY; the checked dependency accepts X-API-Key.
Express, app/api/index.ts	Loads ARTEMIS_API_KEY_<NAME> tuples; falls back to MCP_API_KEY with admin permissions when no explicit keys load.
Governed memory MCP	Has a separate transport and governed-runtime contract. See Governed Artemis Memory MCP server.

The inspected FastAPI dependency allows requests when neither key is configured. A successful local request in that mode does not verify authenticated access. The frontend’s Vite configuration exposes designated dashboard key variables to client code, so those values are visible to the browser and must not be treated as server-only secrets.

Add an Express identity

Put additional identities in the root source so synchronization preserves them:

ARTEMIS_API_KEY_READONLY=<operator-supplied-key>:reader:read

Then synchronize the views and restart the affected process. Express loads its identity map at startup.

Before checking this identity, ensure the running Express process has SKIP_AUTH=false. With both NODE_ENV=development and SKIP_AUTH=true, the middleware assigns a development admin identity and skips credential checks, including when explicit keys exist. A successful request in that mode does not verify the configured key or its permissions. With bypass disabled, confirm that missing and invalid keys receive HTTP 401. The middleware ignores SKIP_AUTH=true outside development mode.

The tuple format is:

ARTEMIS_API_KEY_<NAME>=<key>:<role>:<permission,permission,...>

Use the service’s supported permission checks when selecting permissions. An identity configured for Express does not configure FastAPI or authorize governed MCP operations.

Connection settings

Choose addresses from the caller’s network context: a Compose service name, a host loopback address, and a cloud endpoint are different destinations. Confirm the configured service and port mapping before testing. For PostgreSQL consumers, supply a PostgreSQL connection string accepted by that consumer; a provider’s HTTPS project URL is not a database connection string.

Keep operator values and secrets out of committed documentation. Runtime endpoint and credential values are not included in this guide.

Source locations

• setup_secrets.sh
• scripts/environment_config.py
• config/environment-contract.yaml
• app/api/main.py
• app/api/middleware/auth.ts
• app/web/frontend/vite.config.ts