Configuration Reference

Note: This page covers configuration keys and request-body overrides only. For CLI flag syntax that consumes them, see CLI Command Reference.

Server Environment Variables

Note: Server settings are read from process environment and from .env when present.

Core Process and Storage

export PORT=8000
export DB_PATH=/var/lib/rootcoz/results.db
export ROOTCOZ_ENCRYPTION_KEY=change-me
export PUBLIC_BASE_URL=https://rootcoz.example.com
export LOG_LEVEL=INFO
export METADATA_RULES_FILE=/etc/rootcoz/metadata-rules.yaml

Effect: These variables set the server bind port, persistent data location, secret source, public link base, and metadata-rules source.

Warning: Rotating ROOTCOZ_ENCRYPTION_KEY invalidates encrypted stored credentials and delegated admin API-key hashes. Re-save stored tokens and reissue delegated admin API keys after rotation.

Jenkins and Repository Defaults

export JENKINS_URL=https://jenkins.example.com
export JENKINS_USER=ci-bot
export JENKINS_PASSWORD=your-jenkins-token
export JENKINS_SSL_VERIFY=true
export JENKINS_TIMEOUT=30
export JENKINS_ARTIFACTS_MAX_SIZE_MB=500
export GET_JOB_ARTIFACTS=true
export WAIT_FOR_COMPLETION=true
export POLL_INTERVAL_MINUTES=2
export MAX_WAIT_MINUTES=0
export FORCE_ANALYSIS=false
export TESTS_REPO_URL=https://github.com/acme/tests:develop
export TESTS_REPO_TOKEN=your-repo-token

Effect: These values become the default Jenkins connection, wait behavior, artifact behavior, and tests-repo context for POST /analyze.

AI and Peer-Analysis Defaults

export AI_PROVIDER=claude
export AI_MODEL=claude-opus-4-6
export AI_CLI_TIMEOUT=10
export MAX_CONCURRENT_AI_CALLS=3
export PEER_AI_CONFIGS=cursor:gpt-5.4-xhigh,gemini:gemini-2.5-pro
export PEER_ANALYSIS_MAX_ROUNDS=3
export ADDITIONAL_REPOS=infra:https://github.com/acme/infra:develop@YOUR_TOKEN,product:https://github.com/acme/product

Effect: These values become the default provider/model pair, AI execution limits, peer-review configuration, and extra repository context for analysis requests.

Note: If AI_PROVIDER or AI_MODEL is unset, the request body must supply the missing field.

Jira Analysis and Jira Issue Settings

export JIRA_URL=https://your-team.atlassian.net
export JIRA_EMAIL=you@example.com
export JIRA_API_TOKEN=your-jira-token
export JIRA_PROJECT_KEY=PROJ
export JIRA_SSL_VERIFY=true
export JIRA_MAX_RESULTS=5
export ENABLE_JIRA=true
export ENABLE_JIRA_ISSUES=true

Effect: These values control Jira duplicate search during analysis and Jira issue preview/create availability.

Note: Jira auth mode is selected from JIRA_EMAIL. When JIRA_EMAIL is set, rootcoz uses Cloud credentials and prefers JIRA_API_TOKEN, then JIRA_PAT. When JIRA_EMAIL is unset, rootcoz uses Server/Data Center credentials and prefers JIRA_PAT, then JIRA_API_TOKEN.

GitHub and Report Portal Settings

export GITHUB_TOKEN=ghp_your_token
export ENABLE_GITHUB_ISSUES=true
export REPORTPORTAL_URL=https://reportportal.example.com
export REPORTPORTAL_API_TOKEN=rp_token
export REPORTPORTAL_PROJECT=qe
export REPORTPORTAL_VERIFY_SSL=true
export ENABLE_REPORTPORTAL=true

Effect: These values control GitHub issue creation, feedback availability, and Report Portal push support.

Note: Report Portal push also requires PUBLIC_BASE_URL so rootcoz can generate absolute report links.

Access Control and Cookie Settings

export ADMIN_KEY=your-admin-bootstrap-key
export ALLOWED_USERS=alice,bob,carol
export SECURE_COOKIES=true
export TRUST_PROXY_HEADERS=false

Effect: These variables control bootstrap admin access, non-admin write permissions, and browser/session cookie behavior.

Warning: Enable TRUST_PROXY_HEADERS only when X-Forwarded-User is injected by infrastructure you trust.

Web Push and Alert Delivery

export VAPID_PUBLIC_KEY=your-public-key
export VAPID_PRIVATE_KEY=your-private-key
export VAPID_CLAIM_EMAIL=admin@example.com
export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
export SMTP_HOST=smtp.example.com
export SMTP_PORT=587
export SMTP_USER=rootcoz@example.com
export SMTP_PASSWORD=mail-password
export ALERT_EMAIL_TO=alerts@example.com

Effect: These values enable browser push notifications and optional Slack/email alert delivery.

Note: If both VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY are unset, rootcoz auto-generates and reuses .vapid_keys.json next to DB_PATH, or under $XDG_DATA_HOME/rootcoz/ when DB_PATH is unset.

Warning: Set both VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY together. A partial configuration is treated as invalid and the server falls back to generated keys.

CLI config.toml

File Location and Section Layout

[default]
server = "prod"

[defaults]
username = "alice"
no_verify_ssl = false

[servers.dev]
url = "http://localhost:8000"

[servers.prod]
url = "https://rootcoz.example.com"

Effect: The CLI selects [default].server when no explicit profile is chosen, merges [defaults] into the selected server, and then uses the merged profile for matching commands.

Note: [defaults].server is invalid. Only [default].server selects the default profile.

Connection and Authentication Keys

Note: The keys below are valid in both [defaults] and [servers.<name>].

[servers.prod]
url = "https://rootcoz.example.com"
username = "alice"
no_verify_ssl = false
api_key = "rootcoz_example_admin_key"

Effect: These keys set the CLI's server target, default user identity, TLS behavior, and bearer token.

Analysis Default Keys

Note: The keys below are valid in both [defaults] and [servers.<name>].

[defaults]
jenkins_url = "https://jenkins.example.com"
jenkins_user = "ci-bot"
tests_repo_url = "https://github.com/acme/tests"
ai_provider = "claude"
ai_model = "claude-opus-4-6"
peers = "cursor:gpt-5.4-xhigh,gemini:gemini-2.5-pro"
additional_repos = "infra:https://github.com/acme/infra:develop@YOUR_TOKEN"
wait_for_completion = true

[servers.prod]
url = "https://rootcoz.example.com"
max_concurrent_ai_calls = 5
force = true

Effect: When rootcoz analyze runs without explicit flags, the CLI fills matching request-body fields from the selected profile. Explicit CLI flags still override the profile.

Note: In config.toml, 0 means "do not send a CLI override" for ai_cli_timeout, max_concurrent_ai_calls, jenkins_timeout, jira_max_results, poll_interval_minutes, max_wait_minutes, and peer_analysis_max_rounds. This is different from request-body max_wait_minutes: 0, which means "no limit".

Tracker Default Keys

Note: The keys below are valid in both [defaults] and [servers.<name>].

[servers.prod]
url = "https://rootcoz.example.com"
jira_url = "https://your-team.atlassian.net"
jira_email = "you@example.com"
jira_token = "your-jira-token"
jira_project_key = "PROJ"
jira_security_level = "Internal"
enable_jira = true
github_token = "ghp_your_token"
github_repo_url = "https://github.com/acme/tests"

Effect: These keys fill tracker-related CLI request fields when matching flags are omitted.

Authentication Modes

Note: rootcoz_username and X-Forwarded-User identify non-admin users. Admin privileges come from rootcoz_session or Authorization: Bearer ....

Username Cookie Mode

curl https://rootcoz.example.com/api/auth/me \
  --cookie "rootcoz_username=alice"

Effect: The request runs as alice with role=user and is_admin=false. Admin-only routes still require session or Bearer auth, and non-admin write routes can still be limited by ALLOWED_USERS.

Trusted-Proxy Header Mode

curl https://rootcoz.example.com/api/auth/me \
  -H "X-Forwarded-User: alice"

Effect: When TRUST_PROXY_HEADERS=true, rootcoz sets username from X-Forwarded-User, returns role=user, and writes a matching rootcoz_username cookie on the response. Existing session auth takes precedence.

Session Login Mode

curl -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","api_key":"'"$ADMIN_KEY"'"}' \
  https://rootcoz.example.com/api/auth/login

Effect: Successful login returns JSON with username, role, and is_admin, and sets rootcoz_session plus rootcoz_username. Active sessions are renewed when less than half of the 8-hour TTL remains.

Bearer Token Mode

curl https://rootcoz.example.com/api/auth/me \
  -H "Authorization: Bearer $ADMIN_KEY"

Effect: ADMIN_KEY or an admin user's API key gives admin access. A non-admin user's API key sets username and role=user without admin privileges.

Per-request Analysis Overrides

Note: Shared fields below are accepted by POST /analyze, POST /analyze-failures, and POST /re-analyze/{job_id}. On POST /re-analyze/{job_id}, omitted fields come from the original job's stored request parameters.

Shared Override Fields

peer_ai_configs[] Entries

additional_repos[] Entries

{
  "ai_provider": "gemini",
  "ai_model": "gemini-2.5-pro",
  "enable_jira": false,
  "peer_ai_configs": [],
  "additional_repos": [
    {
      "name": "infra",
      "url": "https://github.com/acme/infra",
      "ref": "develop"
    }
  ]
}

Effect: These fields override shared analysis behavior for one request only. The same fields can be sent to POST /re-analyze/{job_id} to change selected settings while keeping the rest of the original job configuration.

Note: peer_ai_configs=[] and additional_repos=[] explicitly turn off a server default for one request. Omitting the field keeps the server default.

POST /analyze-only Fields

Note: The schema defaults below are shown for lookup. wait_for_completion, poll_interval_minutes, max_wait_minutes, and force only override the server setting when the field is explicitly present in the JSON body.

{
  "job_name": "folder/nightly-suite",
  "build_number": 123,
  "jenkins_url": "https://jenkins.example.com",
  "jenkins_user": "ci-bot",
  "jenkins_password": "YOUR_JENKINS_TOKEN",
  "wait_for_completion": true,
  "poll_interval_minutes": 5,
  "max_wait_minutes": 0,
  "force": true,
  "get_job_artifacts": true
}

Effect: These fields control Jenkins connectivity, artifact download, waiting behavior, and successful-build analysis for the queued job.

Note: In request bodies, max_wait_minutes: 0 means "no limit". This differs from config.toml, where max_wait_minutes = 0 means "do not send a CLI override".

Related Pages

• CLI Command Reference
• API Endpoint Reference
• Submitting Jenkins Builds and JUnit XML
• Connecting GitHub, Jira, and Report Portal
• Managing Users and API Keys