Skip to content

Backend configuration (local.yml)

The backend is a Dropwizard application configured by one YAML file: arnold-backend/arnold-server/config/local.yml. The container image copies it to /app/config/arnold.yml. Values written as ${VAR:-default} are read from the environment, so most deployments change only environment variables (see Environment variables).

Sections

Section Purpose
server Dropwizard HTTP server: API port 8090, admin port 8091, thread pool, request log
logging Log level and format. Set com.phonepe.arnold: DEBUG to trace requests to forges
swagger API documentation for the resources package
elasticSearchConfiguration.columbus Elasticsearch connection and index names (Storage)
serviceCoreConfiguration.auth Dev auth, trusted JWT issuers, API keys, admins, role mappings (Roles and API keys)
serviceCoreConfiguration.copilotConfiguration Opt-in Copilot harness (LLM)
serviceCoreConfiguration.openCodeConfiguration OpenCode harness and model list (LLM)
serviceCoreConfiguration.asyncExecutor Background thread pool (coreSize, maxSize, queueCapacity, …)
serviceCoreConfiguration.aerospikeStorageConfiguration Namespace and set for each entity (Storage)
serviceCoreConfiguration.userSyncConfiguration Per-user forge sync (Webhooks and sync)
serviceCoreConfiguration.repositorySync Import of all open PRs/MRs (Webhooks and sync)
serviceCoreConfiguration.gitlabSyncConfiguration GitLab webhook secret and history window
serviceCoreConfiguration.gitlabConfiguration GitLab URL, OAuth application, service token (GitLab)
serviceCoreConfiguration.githubConfiguration GitHub App (GitHub App)
serviceCoreConfiguration.runner Runner mode and per-mode settings (Runners)
serviceCoreConfiguration.slackClientConfig Slack notifications (disabled by default)
aerospike Aerospike client: hosts, port, retries, timeouts

Selected settings

gitlabConfiguration

Key Default Meaning
baseUrl ${GITLAB_URL} GitLab base URL
clientId, clientSecret OAuth application
callbackUrl ${ARNOLD_UI_URL}/gitlab/oauth/callback Must match the application's redirect URI
oauthStateTtlMs 600000 Lifetime of a pending OAuth state
tokenRefreshBufferMs 60000 Refresh user tokens this long before expiry
requestTimeoutMs 30000 GitLab API timeout
serviceToken ${GITLAB_SERVICE_TOKEN} Optional read token

githubConfiguration

Key Default Meaning
enabled false
webUrl, apiUrl github.com Change both for GitHub Enterprise Server
appId, appSlug, clientId, clientSecret, privateKey GitHub App credentials
callbackUrl ${ARNOLD_UI_URL}/github/oauth/callback Must match the App's callback URL
webhookSecret Webhook HMAC secret

runner

Key Default Meaning
mode LOCAL LOCAL, GITLAB or GITHUB
local.leaseSeconds 300 A claimed job is requeued if its worker stops heartbeating this long
local.maxAttempts 2 Claims per job before it is marked failed
gitlab.projectId, projectPath, ref, triggerToken Runner project and trigger
github.apiUrl, repository, workflow, ref, token Runner repository and dispatch token

copilotConfiguration

Key Default Meaning
enabled false Show and allow the Copilot harness
jobTokenExchangeEnabled false Let runners exchange execution keys for users' tokens. Follows COPILOT_ENABLED
clientId GitHub OAuth App (device flow)
credentialSet arnold-copilot-v1 Credential namespace; changing it disconnects everyone
encryptionKey Base64 32-byte AES key for stored tokens

Full default file

arnold-backend/arnold-server/config/local.yml
server:
  maxThreads: 128
  minThreads: 128
  applicationConnectors:
    - type: http
      port: 8090
  adminConnectors:
    - type: http
      port: 8091
  applicationContextPath: /
  requestLog:
    appenders:
      - type: console
        timeZone: UTC

logging:
  level: INFO
  loggers:
    com.phonepe.arnold: INFO
    org.hibernate: ERROR
  appenders:
    - type: console
      threshold: INFO
      timeZone: UTC
      logFormat: "%(%-5level) [%date] [%thread] [%logger{0}]: %message%n"

swagger:
  title: Arnold
  resourcePackage: com.phonepe.arnold.core.resources

elasticSearchConfiguration:
  columbus:
    storages:
      - type: ELASTIC
        # Optional analytics store. When disabled, no client or health check is created and projections are skipped.
        enabled: ${ELASTIC_ENABLED:-false}
        name: arnold-es-cluster
        hosts:
          endpoints:
            - host: ${ELASTIC_HOST:-localhost}
              port: ${ELASTIC_PORT:-9200}
              scheme: ${ELASTIC_SCHEME:-http}
        auth:
          credentials:
            username: ${ELASTIC_USERNAME:-elastic}
            password: ${ELASTIC_PASSWORD:-changeme}
        requestConfig:
          defaultHeaders:
            - name: "Accept"
              value: "application/vnd.elasticsearch+json; compatible-with=7"
            - name: "Content-Type"
              value: "application/vnd.elasticsearch+json; compatible-with=7"
        indices:
          registry:
            CORE_REVIEWS: "arnold.code.reviews"
            CORE_MERGE_REQUESTS: "arnold.merge.requests"
            CORE_COMMENTS: "arnold.comments"
            CORE_ANALYSIS_RUNS: "arnold.analysis.runs"
            CORE_REVIEW_ENGAGEMENT: "arnold.review.engagement"
serviceCoreConfiguration:
  # Authentication. See AuthConfiguration for all options.
  auth:
    dev:
      # Authenticates requests without a bearer token as a local superadmin. Never enable in production.
      enabled: ${ARNOLD_DEV_AUTH:-true}
    jwt:
      issuers:
        - issuer: arnold-ui
          audience: arnold
          secret: ${ARNOLD_UI_JWT_SECRET:-local-development-secret-change-me-0123456789}
    apiKeys:
      - name: runner
        key: ${ARNOLD_RUNNER_API_KEY:-}
        roles: [runner_execute, analysis_callback_write, smart_diff_callback_write, review_feedback_write]
    # Emails or user ids granted superadmin; comma separated.
    admins: "${ARNOLD_ADMINS:-}"
  # Base64-encoded 32-byte key for GitLab/GitHub tokens at rest; generate with `openssl rand -base64 32`.
  credentialEncryptionKey: "${ARNOLD_CREDENTIAL_ENCRYPTION_KEY:-}"
  copilotConfiguration:
    # Opt-in; see CopilotConfiguration for the caveats before enabling.
    enabled: ${COPILOT_ENABLED:-false}
    jobTokenExchangeEnabled: ${COPILOT_ENABLED:-false}
    clientId: ${COPILOT_CLIENT_ID:-}
    credentialSet: arnold-copilot-v1
    encryptionKey: "${COPILOT_ENCRYPTION_KEY:-}"
  openCodeConfiguration:
    enabled: ${OPENCODE_ENABLED:-true}
    provider: ${OPENCODE_PROVIDER:-openai}
    modelsUrl: ${OPENCODE_MODELS_URL:-}
    apiKey: ${OPENCODE_API_KEY:-}
  asyncExecutor:
    coreSize: 10
    maxSize: 20
    queueCapacity: 512
    keepAliveSeconds: 60
    shutdownAwaitSeconds: 30
  aerospikeStorageConfiguration:
    reviewSet:
      namespace: test
      set: arnold-review-v1
    userSet:
      namespace: test
      set: arnold-user-v1
    changeRequestSet:
      namespace: test
      set: arnold-change-request-v1
    mergeQueueSet:
      namespace: test
      set: arnold-merge-queue-v1
    commentSet:
      namespace: test
      set: arnold-comment-v1
    webhookDeliverySet:
      namespace: test
      set: arnold-webhook-delivery-v1
    projectionEventSet:
      namespace: test
      set: arnold-projection-event-v1
    analysisRunSet:
      namespace: test
      set: arnold-analysis-run-v1
    groupAnalysisRunSet:
      namespace: test
      set: arnold-group-analysis-run-v1
    flowJobUsageSet:
      namespace: test
      set: arnold-flow-job-usage-v1
    versionControlCredentialSet:
      namespace: test
      set: arnold-vcs-credential-v1
    oauthStateSet:
      namespace: test
      set: arnold-oauth-state-v1
    userChangeRequestSet:
      namespace: test
      set: arnold-user-change-request-v1
    userSyncStateSet:
      namespace: test
      set: arnold-user-sync-state-v1
    providerIdentityLinkSet:
      namespace: test
      set: arnold-provider-identity-link-v1
    notificationSet:
      namespace: test
      set: arnold-notification-inbox-v2
    mergeRequestGroupSet:
      namespace: test
      set: arnold-merge-request-group-v2
    clusterControlSet:
      namespace: test
      set: arnold-cluster-control-v1
    personaSet:
      namespace: test
      set: arnold-persona-v1

  userSyncConfiguration:
    intervalMs: 900000
    leaseMs: 300000
    workerBatchSize: 25
    maxConcurrentUsers: 4
    leaderLeaseMs: 120000

  # Imports every open change request from the repositories Arnold can access (GitHub App installations and,
  # with gitlabConfiguration.serviceToken, GitLab projects). gitlabGroups is comma separated; empty = token membership.
  repositorySync:
    enabled: ${ARNOLD_REPOSITORY_SYNC_ENABLED:-true}
    intervalSeconds: ${ARNOLD_REPOSITORY_SYNC_INTERVAL_SECONDS:-300}
    gitlabGroups: "${ARNOLD_GITLAB_SYNC_GROUPS:-}"

  gitlabSyncConfiguration:
    webhookSecret: ${GITLAB_WEBHOOK_SECRET:-local-webhook-secret}
    historyWindowMs: 7776000000
    watermarkOverlapMs: 300000

  gitlabConfiguration:
    baseUrl: ${GITLAB_URL:-https://gitlab.com}
    clientId: "${GITLAB_OAUTH_CLIENT_ID:-}"
    clientSecret: "${GITLAB_OAUTH_CLIENT_SECRET:-}"
    callbackUrl: "${ARNOLD_UI_URL:-http://localhost:3000}/gitlab/oauth/callback"
    oauthStateTtlMs: 600000
    tokenRefreshBufferMs: 60000
    requestTimeoutMs: 30000
    serviceToken: ${GITLAB_SERVICE_TOKEN:-}

  # GitHub App (github.com or GitHub Enterprise Server). Users connect through the app's OAuth flow.
  githubConfiguration:
    enabled: ${GITHUB_APP_ENABLED:-false}
    webUrl: ${GITHUB_WEB_URL:-https://github.com}
    apiUrl: ${GITHUB_API_URL:-https://api.github.com}
    appId: ${GITHUB_APP_ID:-0}
    appSlug: ${GITHUB_APP_SLUG:-}
    clientId: ${GITHUB_APP_CLIENT_ID:-}
    clientSecret: ${GITHUB_APP_CLIENT_SECRET:-}
    privateKey: ${GITHUB_APP_PRIVATE_KEY:-}
    callbackUrl: ${ARNOLD_UI_URL:-http://localhost:3000}/github/oauth/callback
    webhookSecret: ${GITHUB_APP_WEBHOOK_SECRET:-}

  # Where review workflows run: LOCAL (self-hosted `arnold-runner worker`), GITLAB (CI pipelines) or GITHUB (Actions).
  runner:
    mode: ${ARNOLD_RUNNER_MODE:-LOCAL}
    local:
      leaseSeconds: 300
      maxAttempts: 2
    gitlab:
      projectId: ${RUNNER_GITLAB_PROJECT_ID:-0}
      projectPath: ${RUNNER_GITLAB_PROJECT_PATH:-}
      ref: ${RUNNER_GITLAB_REF:-main}
      triggerToken: ${RUNNER_GITLAB_TRIGGER_TOKEN:-}
    github:
      apiUrl: ${RUNNER_GITHUB_API_URL:-https://api.github.com}
      repository: ${RUNNER_GITHUB_REPOSITORY:-}
      workflow: ${RUNNER_GITHUB_WORKFLOW:-arnold-runner.yml}
      ref: ${RUNNER_GITHUB_REF:-main}
      token: ${RUNNER_GITHUB_TOKEN:-}

  slackClientConfig:
    enabled: false
    url: ${SLACK_API_URL:-https://slack.com}
    botToken: "${ARNOLD_SLACK_TOKEN:-}"
    uiBaseUrl: ${ARNOLD_UI_URL:-http://localhost:3000}

aerospike:
  hosts: ${AEROSPIKE_HOSTS:-localhost}
  port: 3000
  retries: 5
  sleepBetweenRetries: 500
  timeout: 500
  maxConnectionsPerNode: 10