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

# Configuration

> The MusterBox config profile, validation, and defaults.

All integrations start from a configuration profile. The SDK validates the
profile before any network traffic leaves the device — invalid config fails
fast with `InvalidConfig` instead of half-working at runtime.

## Config schema

Config schema version **1**. The profile is a TOML file (or an equivalent
programmatic object) with these sections and defaults:

| Setting                         | Default   | Notes                                              |
| ------------------------------- | --------- | -------------------------------------------------- |
| `environment`                   | `sandbox` | One of `local`, `sandbox`, `staging`, `production` |
| `log.level`                     | `info`    | Logging verbosity                                  |
| `offline_buffering`             | `true`    | Buffer events while offline and flush later        |
| `event_queue_capacity`          | `1000`    | Max queued events before backpressure              |
| `shutdown_timeout_ms`           | `5000`    | Grace period for the shutdown sequence             |
| `transport.request_timeout_ms`  | `10000`   | Per-request timeout                                |
| `transport.connect_timeout_ms`  | `10000`   | Connection timeout                                 |
| `transport.max_retry_attempts`  | `5`       | Retries for transient failures                     |
| `transport.retry_base_delay_ms` | `500`     | Exponential backoff base                           |
| `transport.retry_max_delay_ms`  | `30000`   | Backoff ceiling                                    |
| `batch_size`                    | `25`      | Events per flush batch                             |
| `flush_interval_ms`             | `1000`    | Periodic flush cadence                             |

```toml theme={"dark"}
# musterbox.toml
[base]
environment = "sandbox"

[logs]
level = "info"

[transport]
request_timeout_ms = 10000
max_retry_attempts = 5
```

## Loading configuration

```rust theme={"dark"}
use musterbox_core::config::Config;

let config = Config::from_env()?;          // MYSTERY_VAR_* injection point
let config = Config::from_file("musterbox.toml")?;
let config = Config::from_content(toml_str)?;
```

The encoder is frame-based, UTF-8, and version-aware. Foreign or future-config
**version tags** causes the loader to return a `MismatchedVersion` error
instead of mis-reading fields.

## Validation modes

MusterBoxSDK enforces different validation strictness depending on the
lifecycle stage:

| Mode                        | Purpose                                                  |
| --------------------------- | -------------------------------------------------------- |
| `MusterBoxConfig` (default) | Load and validate everything, fail fast                  |
| `UnvalidatedConfig`         | Raw, unvalidated descriptor (for tooling)                |
| `ValidatedConfig`           | What `from_env`/`from_file` produce after passing checks |

Config **secrets and credentials are never logged**: diagnostics redact
`base_url`, tokens, and key material.

## Overriding the backend URL

For local development against a custom backend:

```toml theme={"dark"}
[base]
environment = "production"        # keep production env semantics
[transport]
base_url_override = "http://localhost:4100/api/v1"
```

An override that is neither `http://` nor `https://` is rejected by
validation.

## Precedence

1. Explicit `base_url_override` (when provided).

2. The environment's default base URL:

   | Environment  | URL                                 |
   | ------------ | ----------------------------------- |
   | `local`      | `http://localhost:8081`             |
   | `sandbox`    | `https://sandbox-api.musterbox.dev` |
   | `staging`    | `https://staging-api.musterbox.dev` |
   | `production` | `https://api.musterbox.com`         |

3. The auth API base is always derived as `control plane base + /api/v1`.

Next: [Initialization & lifecycle](/sdk/initialization).