Baton-runner configuration reference

Configure baton-runner to run multiple Baton connectors from a single process, with support for multiple secret backends.

Baton-runner runs multiple Baton connectors from a single process. Instead of managing each connector individually, you define all your connectors and their credentials in one config.yaml file and run them together.

Download

Download baton-runner from dist.conductorone.com/ConductorOne/baton-runner. Builds are available for Windows (amd64), macOS (amd64 and arm64), and Linux (amd64 and arm64).

For step-by-step setup instructions on Windows Server, see Run multiple connectors as a Windows service.

Configuration

Baton-runner is configured with a single YAML file. By default it looks for config.yaml in the current directory. Use the -c flag to specify a different path:

baton-runner -c /path/to/config.yaml

A config.yaml has three top-level keys: log-level, connectors, and secrets.

log-level: info

connectors:
  - name: github-org1
    path: /usr/local/bin/baton-github
    config:
      envFrom:
        secrets:
          BATON_TOKEN: org1:BATON_TOKEN
          BATON_CLIENT_ID: org1:BATON_CLIENT_ID
          BATON_CLIENT_SECRET: org1:BATON_CLIENT_SECRET

  - name: github-org2
    path: /usr/local/bin/baton-github
    config:
      env:
        BATON_ORGS: my-org
      envFrom:
        secrets:
          BATON_TOKEN: org2:BATON_TOKEN
          BATON_CLIENT_ID: org2:BATON_CLIENT_ID
          BATON_CLIENT_SECRET: org2:BATON_CLIENT_SECRET

secrets:
  insecure:
    secrets:
      org1: org1.yaml
      org2: org2.yaml

Real-world example

Here’s what a production config looks like when running multiple config-driven connectors of the same type — in this case, several SQL Server databases and two HTTP API applications, each with its own connector-specific config file:

log-level: info

connectors:
  - name: Database_01
    path: C:\ConductorOne\baton-sql.exe
    config:
      env:
        BATON_CONFIG_PATH: C:\ConductorOne\Database_01.yaml
        BATON_FILE: C:\ConductorOne\Database_01.c1z
        BATON_PROVISIONING: true
      envFrom:
        secrets:
          DB_PASSWORD: Database_01:DB_PASSWORD
          BATON_CLIENT_ID: Database_01:BATON_CLIENT_ID
          BATON_CLIENT_SECRET: Database_01:BATON_CLIENT_SECRET

  - name: Database_02
    path: C:\ConductorOne\baton-sql.exe
    config:
      env:
        BATON_CONFIG_PATH: C:\ConductorOne\Database_02.yaml
        BATON_FILE: C:\ConductorOne\Database_02.c1z
        BATON_PROVISIONING: true
      envFrom:
        secrets:
          DB_PASSWORD: Database_02:DB_PASSWORD
          BATON_CLIENT_ID: Database_02:BATON_CLIENT_ID
          BATON_CLIENT_SECRET: Database_02:BATON_CLIENT_SECRET

  - name: HTTP_API_App_01
    path: C:\ConductorOne\baton-http.exe
    config:
      env:
        BATON_CONFIG_PATH: C:\ConductorOne\HTTP_API_App_01.yaml
        BATON_FILE: C:\ConductorOne\HTTP_API_App_01.c1z
        BATON_PROVISIONING: true
      envFrom:
        secrets:
          DB_PASSWORD: HTTP_API_App_01:DB_PASSWORD
          BATON_CLIENT_ID: HTTP_API_App_01:BATON_CLIENT_ID
          BATON_CLIENT_SECRET: HTTP_API_App_01:BATON_CLIENT_SECRET

secrets:
  wincred:
    secrets:
      Database_01: Database_01
      Database_02: Database_02
      HTTP_API_App_01: HTTP_API_App_01

A few patterns to note:

• BATON_CONFIG_PATH points each connector to its own config file, which is how config-driven connectors like baton-sql and baton-http handle per-instance settings.
• BATON_FILE gives each connector a unique output path so sync files don’t overwrite each other.
• BATON_PROVISIONING: true enables write-back provisioning for each connector.

Connector options

Field	Required	Description
name	Yes	A display name for the connector. Used in logs.
path	Yes	Absolute path to the connector executable.
config.env	No	Static environment variables passed to the connector as key-value pairs.
config.envFrom.secrets	No	Environment variables populated from a secret backend. See Secret reference format.

Secret reference format

Values in config.envFrom.secrets use the format secretname:FIELD:

• secretname — the name defined in the secrets section of config.yaml
• FIELD — the key to retrieve from within that secret

For example, org1:BATON_TOKEN reads the BATON_TOKEN field from the secret named org1.

Secret backends

Baton-runner supports multiple backends for storing connector credentials. You can define one backend per config.yaml, and all connectors in that file share it.

Backend	Best for
wincred	Windows Server deployments
insecure	Local development and testing only
awssecretmanager	AWS-hosted environments
vault	HashiCorp Vault environments

Windows Credential Manager (wincred)

Stores credentials in the Windows Credential Manager. Recommended for Windows Server deployments.

The secrets map associates a connector secret name with its target name in Windows Credential Manager.

secrets:
  wincred:
    secrets:
      org1: org1
      org2: org2

Use the wincred set command to load credentials into the store:

baton-runner.exe wincred set org1 org1.yaml

Where org1.yaml is a YAML file containing the connector’s environment variables. See Run multiple connectors as a Windows service for a full walkthrough.

Insecure (YAML files)

The insecure backend stores credentials in plaintext YAML files on disk. Use it for local development and testing only — not in production.

The secrets map associates a connector secret name with the path to its YAML file.

secrets:
  insecure:
    secrets:
      org1: org1.yaml
      org2: org2.yaml

Each YAML file contains the connector’s environment variables as key-value pairs:

# org1.yaml
BATON_TOKEN: your-token
BATON_CLIENT_ID: your-client-id
BATON_CLIENT_SECRET: your-client-secret

AWS Secrets Manager

Reads credentials from AWS Secrets Manager. AWS credentials are loaded from the default credential chain (environment variables, shared credentials file, IAM role, and so on) — no AWS credentials are configured in config.yaml itself.

The secrets map associates a connector secret name with the path to a YAML pointer file:

secrets:
  awssecretmanager:
    secrets:
      org1: org1-aws.yaml

Each pointer file specifies the AWS secret name and region:

# org1-aws.yaml
secretname: my-conductorone-org1-secret
region: us-east-1

The secret value stored in AWS Secrets Manager must be a JSON or YAML string containing the connector’s environment variables as key-value pairs.

HashiCorp Vault

Reads credentials from a HashiCorp Vault KV secrets engine. Both KV v1 and v2 are supported.

secrets:
  vault:
    url: https://vault.example.com:8200
    mount: secret
    kvapi: 2
    credsfile: vaultcreds.yaml
    secrets:
      org1: conductorone/org1
      org2: conductorone/org2

The secrets map associates a connector secret name with the KV path in Vault.

Authentication — specify credentials using one of these options (listed in priority order):

Option	How
Credential file	Set credsfile to the path of a YAML file containing token, or username and password
Inline token	Set token directly in config.yaml
Inline username/password	Set username and password directly in config.yaml

Credential file format:

# vaultcreds.yaml — use either token or username/password
token: your-vault-token

# vaultcreds.yaml
username: your-username
password: your-password

Log level

Set the log level using the log-level key in config.yaml or the BATON_LOG_LEVEL environment variable. Valid values: debug, info, warn, error, panic. The default is info.

# In config.yaml
log-level: debug

# As an environment variable
BATON_LOG_LEVEL=debug baton-runner -c config.yaml