> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynative.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cynative Configuration: YAML File and Environment Variables

> Complete reference for ~/.cynative/config.yaml and every CYNATIVE_* env var — LLM provider, connectors, audit log, cache, and session limits.

Cynative reads its configuration from `~/.cynative/config.yaml` on startup. Every value in that file can also be set through a `CYNATIVE_*` environment variable — env vars take precedence over the file. For simple setups (picking a provider, pointing at an API endpoint) you do not need a YAML file at all: export a handful of env vars and you are running.

## Config file location

The default config file path is `~/.cynative/config.yaml`. Pass `--config <path>` to use a different file:

```bash theme={null}
cynative --config /etc/cynative/config.yaml "what is publicly exposed?"
```

If neither the default file nor a `--config` path exists, Cynative starts with built-in defaults and whatever `CYNATIVE_*` env vars are set. A missing file is not an error; an unreadable or malformed file is.

<Note>
  Maps and slices (for example `llm.keys[]`, `connectors.github.permissions`, and `llm.network_config.extra_headers`) require YAML — they cannot be expressed as a single env var. Every other field is env-bindable.
</Note>

***

## LLM configuration

The `llm:` block configures the model provider. `provider` and `model` are required; everything else has a default or is optional.

```yaml theme={null}
llm:
  provider: anthropic          # required — e.g. openai, anthropic, bedrock, vertex, azure, ollama
  model: claude-opus-5         # required — provider-specific model identifier
  api_key: env.ANTHROPIC_API_KEY  # plain string or env.VAR_NAME reference

  reasoning_effort: medium     # none | minimal | low | medium | high (default: provider default)
  reasoning_max_tokens: 16000  # cap the reasoning/thinking token budget (0 = unset)

  network_config:
    base_url: https://my-proxy.example.com  # override the provider's default endpoint
    default_request_timeout_in_seconds: 300 # default: 300 (Cynative raises Bifrost's 30s default)
    max_retries: 3                           # default: 3 (retries 429/5xx and transport errors)
    extra_headers:
      x-tenant: prod
    insecure_skip_verify: false             # skip TLS verification — never use in production

  # Multi-key load balancing (requires YAML; see docs/providers/ for key_config shapes)
  keys:
    - value: env.OPENAI_API_KEY_1
    - value: env.OPENAI_API_KEY_2
```

### LLM field reference

| Field | Env var | Default | Notes |
| - | - | - | - |
| `llm.provider` | `CYNATIVE_LLM_PROVIDER` | — | **Required.** Provider id (e.g. `openai`, `anthropic`, `bedrock`). |
| `llm.model` | `CYNATIVE_LLM_MODEL` | — | **Required.** Model name as the provider expects it. |
| `llm.api_key` | `CYNATIVE_LLM_API_KEY` | — | Plain string or `env.VAR_NAME` reference. |
| `llm.reasoning_effort` | `CYNATIVE_LLM_REASONING_EFFORT` | *(provider default)* | `none` \| `minimal` \| `low` \| `medium` \| `high`. |
| `llm.reasoning_max_tokens` | `CYNATIVE_LLM_REASONING_MAX_TOKENS` | `0` (unset) | Per-request reasoning token cap. |
| `llm.network_config.base_url` | `CYNATIVE_LLM_NETWORK_CONFIG_BASE_URL` | *(provider default)* | Custom endpoint; do not include `/v1`. |
| `llm.network_config.default_request_timeout_in_seconds` | `CYNATIVE_LLM_NETWORK_CONFIG_DEFAULT_REQUEST_TIMEOUT_IN_SECONDS` | `300` | Seconds before a request is abandoned. |
| `llm.network_config.max_retries` | `CYNATIVE_LLM_NETWORK_CONFIG_MAX_RETRIES` | `3` | Retries on 429/5xx and transport errors. Set `0` to disable. |
| `llm.network_config.insecure_skip_verify` | `CYNATIVE_LLM_NETWORK_CONFIG_INSECURE_SKIP_VERIFY` | `false` | Skip TLS certificate verification. |

`extra_headers` and `keys[]` require YAML. See [LLM Providers](/providers/overview) for every supported provider's full configuration reference, including provider-specific key configs (Azure endpoint, Bedrock region, Vertex project, Ollama URL, etc.).

***

## Session limits

These knobs bound how much work a single run can do — essential for unattended, scheduled, or CI runs.

| Config key | Env var | Default | Effect |
| - | - | - | - |
| `max_iterations` | `CYNATIVE_MAX_ITERATIONS` | `32` | Max main-loop tool-calling iterations per turn. Minimum: 1. |
| `max_subagent_iterations` | `CYNATIVE_MAX_SUBAGENT_ITERATIONS` | `10` | Max iterations inside a task sub-agent. Minimum: 1. |
| `max_total_tokens` | `CYNATIVE_MAX_TOTAL_TOKENS` | `0` | Per-session token ceiling across the main loop, sub-agents, the verifier, and interactive follow-ups. `0` means unbounded. |
| `max_consecutive_failures` | `CYNATIVE_MAX_CONSECUTIVE_FAILURES` | `5` | Halt-and-summarize after this many consecutive no-progress tool calls. `0` disables the limit. |
| `sandbox_max_concurrency` | `CYNATIVE_SANDBOX_MAX_CONCURRENCY` | `16` | Max concurrent in-sandbox tool calls. Range: 1–64. |

Finding verification (`verify_findings`) makes additional model calls — budget for them on any run that produces findings.

***

## Display configuration

| Config key | Env var | Default | Notes |
| - | - | - | - |
| `render_style` | `CYNATIVE_RENDER_STYLE` | `adaptive` | Output rendering mode. `adaptive` uses rich terminal output when a TTY is detected; `notty` forces plain text (useful in CI or when piping output). |

***

## Audit configuration

Every tool call is recorded to a persistent JSONL audit log. The log is **fail-closed**: if a call cannot be recorded, the run aborts. Tool results are redacted before they are written; approval-prompt arguments are stored verbatim, so the log can hold sensitive values. The log is readable only by the user who ran Cynative.

| Config key | Env var | Default | Notes |
| - | - | - | - |
| `audit.enabled` | `CYNATIVE_AUDIT_ENABLED` | `true` | Set `false` to disable the audit log entirely. |
| `audit.path` | `CYNATIVE_AUDIT_PATH` | `~/.cynative/audit.log` | Path to the JSONL audit log file. |
| `audit.max_size_mb` | `CYNATIVE_AUDIT_MAX_SIZE_MB` | `100` | Rotate the log when it reaches this size in MB. Minimum: 1. |
| `audit.retention_days` | `CYNATIVE_AUDIT_RETENTION_DAYS` | `30` | Retain rotated log files for this many days. Minimum: 1. |
| `audit.compress` | `CYNATIVE_AUDIT_COMPRESS` | `false` | Gzip-compress rotated log files. |

Every entry from an agent run also records the agent's name, source, and file digest, so a finding can be traced to the exact prompt that produced it.

***

## Cache configuration

Cynative maintains an on-disk cache for connector hardening metadata — IAM policy documents, service catalogs, OpenAPI descriptions, and model archives — so startup is fast on repeated runs.

| Config key | Env var | Default | Notes |
| - | - | - | - |
| `cache.dir` | `CYNATIVE_CACHE_DIR` | `~/.cynative/cache` | Directory for cached connector metadata. |
| `cache.ttl` | `CYNATIVE_CACHE_TTL` | `24h` | Time-to-live for cached entries. Use Go duration syntax (e.g. `6h`, `30m`). Minimum: `1m`. |

***

## Connector configuration

The `connectors:` block lets you configure each connector's read-only policy ceiling. Defaults are secure; you only need this block if you are using a custom policy ARN, role, or permission set. Each connector also has its own credential discovery and full reference in the [Connectors](/connectors/overview) section.

```yaml theme={null}
connectors:
  aws:
    policy: arn:aws:iam::aws:policy/SecurityAudit  # default
  gcp:
    role: roles/viewer                              # default
  azure:
    role_definition: Reader                         # default
    cloud: auto                                     # auto | AzureCloud | AzureUSGovernment | AzureChinaCloud
  github:
    permissions:
      default: read                                 # read | write | none per category
  gitlab:
    host: gitlab.com                                # default; set to your self-managed host
    api_host: ""                                    # optional override for the API hostname
    allow_private_network: false                    # allow self-managed GitLab on private networks
    ca_cert: ""                                     # path to a PEM CA bundle for self-managed TLS
    permissions:
      default: read
```

### Connector config keys and env vars

| Config key | Env var | Default | Notes |
| - | - | - | - |
| `connectors.aws.policy` | `CYNATIVE_CONNECTORS_AWS_POLICY` | `arn:aws:iam::aws:policy/SecurityAudit` | IAM policy ARN the action gate authorizes against. |
| `connectors.gcp.role` | `CYNATIVE_CONNECTORS_GCP_ROLE` | `roles/viewer` | Predefined or custom role the action gate authorizes against. |
| `connectors.azure.role_definition` | `CYNATIVE_CONNECTORS_AZURE_ROLE_DEFINITION` | `Reader` | Azure RBAC role name or role-definition GUID. |
| `connectors.azure.cloud` | `CYNATIVE_CONNECTORS_AZURE_CLOUD` | `auto` | `auto` detects from the credential; override for sovereign clouds. |
| `connectors.github.permissions` | `CYNATIVE_CONNECTORS_GITHUB_PERMISSIONS` | *(secure baseline)* | Map of category → `read\|write\|none`. Compact env form: `"default=read,issues=write"`. |
| `connectors.gitlab.host` | `CYNATIVE_CONNECTORS_GITLAB_HOST` | `gitlab.com` | Bare hostname (or `host:port`) for self-managed GitLab. |
| `connectors.gitlab.api_host` | `CYNATIVE_CONNECTORS_GITLAB_API_HOST` | *(empty)* | Optional override for the GitLab API hostname when it differs from `host`. |
| `connectors.gitlab.allow_private_network` | `CYNATIVE_CONNECTORS_GITLAB_ALLOW_PRIVATE_NETWORK` | `false` | Allow connections to a self-managed GitLab on a private network address. |
| `connectors.gitlab.ca_cert` | `CYNATIVE_CONNECTORS_GITLAB_CA_CERT` | *(empty)* | Path to a PEM CA certificate bundle for verifying a self-managed GitLab's TLS certificate. |
| `connectors.gitlab.permissions` | `CYNATIVE_CONNECTORS_GITLAB_PERMISSIONS` | *(secure baseline)* | Map of category → `read\|write\|none`. Compact env form: `"default=read,issues=write"`. |
| `connectors.eks.cluster_role` | `CYNATIVE_CONNECTORS_EKS_CLUSTER_ROLE` | `view` | Kubernetes ClusterRole used as the EKS action gate policy. |
| `connectors.gke.cluster_role` | `CYNATIVE_CONNECTORS_GKE_CLUSTER_ROLE` | `view` | Kubernetes ClusterRole used as the GKE action gate policy. |
| `connectors.aks.cluster_role` | `CYNATIVE_CONNECTORS_AKS_CLUSTER_ROLE` | `view` | Kubernetes ClusterRole used as the AKS action gate policy. |
| `connectors.kubernetes.cluster_role` | `CYNATIVE_CONNECTORS_KUBERNETES_CLUSTER_ROLE` | `view` | ClusterRole used as the self-managed Kubernetes action gate policy. |

***

## Full example config.yaml

A complete working configuration combining all sections:

```yaml theme={null}
# ~/.cynative/config.yaml

# LLM provider — required
llm:
  provider: anthropic
  model: claude-opus-5
  api_key: env.ANTHROPIC_API_KEY
  reasoning_effort: medium
  network_config:
    default_request_timeout_in_seconds: 300
    max_retries: 3

# Display
render_style: adaptive          # adaptive | notty

# Session resource limits
max_iterations: 32
max_subagent_iterations: 10
max_total_tokens: 500000        # 0 = unbounded
max_consecutive_failures: 5
sandbox_max_concurrency: 16

# Audit log
audit:
  enabled: true
  path: ~/.cynative/audit.log
  max_size_mb: 100
  retention_days: 30
  compress: false

# On-disk metadata cache
cache:
  dir: ~/.cynative/cache
  ttl: 24h

# Connector hardening policies (all at secure defaults — only set what you need to change)
connectors:
  aws:
    policy: arn:aws:iam::aws:policy/SecurityAudit
  gcp:
    role: roles/viewer
  azure:
    role_definition: Reader
    cloud: auto
  github:
    permissions:
      default: read
  gitlab:
    host: gitlab.com
    api_host: ""                  # optional; override if API hostname differs from host
    allow_private_network: false
    ca_cert: ""                   # path to PEM CA bundle for self-managed TLS
    permissions:
      default: read
  eks:
    cluster_role: view
  gke:
    cluster_role: view
  aks:
    cluster_role: view
  kubernetes:
    cluster_role: view
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.