pda_config.yaml

pda_config.yaml sits at the root of a project folder. It names the project and configures its databases, language models and integrations. pda init writes a first version, and the CLI and the Polaris server both read it.

Example

project_name: polaris-epigenomics

databases:
    - name: epigenomics
      type: duckdb
      path: "{{ env('POLARIS_DATA_DIR') }}/epigenomics.duckdb"
      templates:
          - columns
          - preview
          - profiling

llm:
    providers:
        - provider: bedrock
          aws_region: us-west-2
          models:
              - id: us.anthropic.claude-opus-5-5
                default: true
              - id: us.anthropic.claude-sonnet-5-5
              - id: us.anthropic.claude-haiku-5-5
    annotation_model: us.anthropic.claude-haiku-5-5

test:
    models:
        - bedrock:us.anthropic.claude-opus-5-5
    threads: 4

Keep secrets out of the file

Never write a password, token or key into pda_config.yaml. Reference it instead. Polaris replaces these before it reads the YAML:

Reference	Reads from
{{ env('VAR') }}	The environment variable VAR. A missing variable becomes an empty string and a warning.
{{ aws('secret-name/path.to.field') }}	AWS Secrets Manager.
{{ k8s('namespace/secret/field') }}	A Kubernetes secret.

The CLI also loads a .env file from the current directory. Keep .env out of Git.

Top-level keys

Key	Required	What it sets
project_name	Yes	The project’s name. pda deploy uses it to find the project on the server. Pick it carefully.
threads	No	Worker threads for pda sync. Default 1.
databases	No	Database connections. See Databases.
repos	No	Git repositories to sync into repos/.
notion, confluence, obsidian	No	Document sources to sync into docs/.
llm	No	Model providers and models.
semantic_layer	No	The semantic layer. See Semantic layer.
test	No	Defaults for pda test. See Tests.
slack	No	Slack bot credentials, for running Polaris locally.
mcp	No	Outbound MCP servers for the agent.
skills	No	The skills folder.
metabase, tableau	No	Credentials for pda migrate.

If an optional section is invalid, for example because a referenced secret is not set, commands that do not need it drop it with a warning instead of failing.

llm

llm:
    providers:
        - provider: bedrock
          aws_region: us-west-2
          aws_profile: my-profile # optional
          models:
              - id: us.anthropic.claude-sonnet-5-5
                name: Claude Sonnet 5.5 # optional display name
                default: true
    annotation_model: us.anthropic.claude-haiku-5-5

• providers[].provider names the provider. Polaris supports Amazon Bedrock and several others, including Anthropic, OpenAI, Google Gemini and Vertex AI, Mistral, Ollama, OpenRouter and OpenAI-compatible endpoints.
• models[] lists the models to offer. Each model has an id, an optional name, an optional default, and optional costs in US dollars per million tokens (input_no_cache, input_cache_read, input_cache_write, output).
• budget caps spend per provider: limit, per_user_limit and period (day, week or month).
• annotation_model is the model that writes AI table summaries during pda sync.

Note

A model provider configured in the app, under Settings › Agent › Models, takes precedence over this block.

repos

repos:
    - name: dbt
      url: https://github.com/acme/dbt-project.git
      branch: main
      include: ['models/**']
    - name: local-notebooks
      local_path: ../notebooks

Each repository needs either url or local_path, not both. branch only works with url.

notion, confluence and obsidian

notion:
    api_key: "{{ env('NOTION_API_KEY') }}"
    pages:
        - https://www.notion.so/acme/Metrics-Glossary-0123456789abcdef
    max_depth: 1 # child pages to follow, up to 10
    max_pages: 100 # up to 250

confluence:
    base_url: https://acme.atlassian.net/wiki
    deployment: cloud
    email: me@acme.com
    api_token: "{{ env('CONFLUENCE_API_TOKEN') }}"
    spaces: [DATA]

obsidian:
    path: ~/vaults/analytics

Confluence also accepts pages, page_trees and labels (as SPACE:label), and a personal access token or username and password for Server.

test

test:
    models:
        - bedrock:us.anthropic.claude-opus-5-5
        - model: bedrock:us.anthropic.claude-sonnet-5-5
          reasoning_efforts: [low, high]
    threads: 4
    k: 1
    comparison:
        rtol: 0.00001
        atol: 0.00000001
        decimals: 2

See Tests for what these mean.