Configuration reference

apiVersion: helix.ml/v1alpha1
kind: Project
metadata:
  name: my-app                    # Used as the project identifier
 
spec:
  description: "What this project is for"
 
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true               # The primary repo is cloned first and receives PRs
    - url: "https://github.com/org/shared-lib"
      branch: main
 
  agent:
    name: "My Agent"
    runtime: claude_code          # claude_code | goose_code | qwen_code | zed_agent
    model: claude-sonnet-4-6      # omit for claude_code
    provider: anthropic           # anthropic | openai | helix | (any configured provider)
    code_agent_credential_type: api_key  # api_key (default) | subscription (Claude Code only)
 
    # Goose-specific:
    goose:
      recipes:
        - name: triage
          path: .goose/recipes/triage.yaml

name: My Assistant
description: "What this agent app does"
 
assistants:
- name: Support
  system_prompt: |
    You are a helpful assistant.
  temperature: 0.3
  max_tokens: 4096
  max_iterations: 10
  agent_type: helix_agent          # helix_basic | helix_agent
 
  # --- helix_agent model configuration ---
  # helix_agent uses four dedicated model roles instead of a single top-level
  # provider/model. Do NOT set provider or model on a helix_agent assistant —
  # the server silently clears those fields and they have no effect.
  reasoning_model_provider: anthropic
  reasoning_model: claude-sonnet-4-6
  reasoning_model_effort: ""       # optional: low | medium | high (default: provider default)
  generation_model_provider: anthropic
  generation_model: claude-haiku-4-5-20251001
  small_reasoning_model_provider: anthropic
  small_reasoning_model: claude-haiku-4-5-20251001
  small_reasoning_model_effort: "" # optional
  small_generation_model_provider: anthropic
  small_generation_model: claude-haiku-4-5-20251001
 
  # --- helix_basic model configuration (use instead of the block above) ---
  # helix_basic uses a single provider/model pair:
  #   provider: anthropic
  #   model: claude-sonnet-4-6
 
  # Skills
  web_search:
    enabled: true
    max_results: 10
 
  browser:
    enabled: true
 
  # Knowledge bases (RAG) — see guide-rag-knowledge
  knowledge:
  - name: my-docs
    description: "Product documentation"
    refresh_enabled: true
    refresh_schedule: "0 */6 * * *"
    rag_settings:
      results_count: 4
      chunk_size: 1024
      chunk_overflow: 64
      enable_vision: false         # true to index images and scanned PDFs
    source:
      web:
        urls:
        - https://docs.example.com/
        crawler:
          enabled: true
          max_depth: 2
          max_pages: 200
          readability: true
 
  # API integrations (OpenAPI)
  apis:
  - name: My API
    description: "Internal API"
    url: https://api.example.com
    schema: ./openapi.yaml
    headers:
      Authorization: Bearer ${MY_API_KEY}
 
  # MCP servers — HTTP transport
  mcps:
  - name: My MCP Server
    url: https://mcp.example.com/tools
    headers:
      Authorization: Bearer ${MCP_TOKEN}
 
  # MCP servers — stdio transport (runs as subprocess)
  # mcps:
  # - name: Filesystem
  #   type: stdio
  #   cmd: npx
  #   args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
 
  # Triggers — see guide-triggers
  triggers:
  - slack:
      bot_token: ${SLACK_BOT_TOKEN}
      channels:
      - support
  - teams:
      tenant_id: ${TEAMS_TENANT_ID}
      client_id: ${TEAMS_CLIENT_ID}
      client_secret: ${TEAMS_CLIENT_SECRET}
  - discord:
      bot_token: ${DISCORD_BOT_TOKEN}
      guild_id: "123456789"
  - cron:
      schedule: "0 9 * * 1-5"
      input: "Generate daily summary"
  - webhook: {}                    # Helix generates a unique URL
  - azure_devops:
      org_url: https://dev.azure.com/myorg
      token: ${AZURE_DEVOPS_TOKEN}
      events: [work_item_created, work_item_updated]
  - crisp:
      website_id: ${CRISP_WEBSITE_ID}
      api_key: ${CRISP_API_KEY}
      api_secret: ${CRISP_API_SECRET}