# Configuration

> Constructor options, config fields, and per-instance isolation.

Source: https://maincode.com/docs/python-client-sdk-configuration
Section: Client SDK · Matilda documentation

---

## `MatildaClient`

```python
client = MatildaClient(
    token="",                     # static Bearer JWT
    # keyword-only below:
    base_url=DEFAULT_BASE_URL,    # https://matilda.maincode.com/api
    get_token=None,               # async token provider
    config=None,                  # or pass a pre-built MatildaConfig
)
```

| Field | Type | Description |
| - | - | - |
| `token` | `str` | A static access token. Use this for simple setups, or use get\_token for managed refresh. Defaults to the empty string. |
| `base_url` | `str` | The Matilda API base URL. Must be absolute for auth flows. Defaults to https\://matilda.maincode.com/api. |
| `get_token` | `TokenProvider` | Async token provider called on every request (and once with force\_refresh=True after a 401, before the single retry). A managed TokenManager is wired here automatically after client.auth.login\_with\_\*. |
| `config` | `MatildaConfig` | A pre-built config. When omitted, one is constructed from the other parameters. |

## `MatildaConfig`

A frozen dataclass — create a new client to change configuration.

| Field | Type | Description |
| - | - | - |
| `base_url` | `str` | The Matilda API base URL. Defaults to https\://matilda.maincode.com/api. |
| `token` | `str` | Static Bearer token. Defaults to the empty string. |
| `get_token` | `TokenProvider \| None` | Async token provider (see above). |
| `timeout` | `float` | Request timeout in seconds. Defaults to 120.0. |
| `api_version` | `str` | API version sent via the X-Matilda-API-Version header. Defaults to MATILDA\_CURRENT\_API\_VERSION. |
| `chunk_size` | `int` | Chunked-upload part size in bytes. Defaults to 8388608 (8 MiB). |
| `chunked_threshold` | `int` | File size at/above which uploads switch to the chunked protocol. Defaults to 16777216 (16 MiB). |
| `part_concurrency` | `int` | Parallel parts per chunked upload. Defaults to 4. |
| `max_part_retries` | `int` | Retries per upload part before the session is aborted. Defaults to 3. |

## Environment URLs

| Environment | Base URL |
| - | - |
| Production | `https://matilda.maincode.com/api` |
| Staging | `https://staging.matilda.maincode.com/api` |

## Instance isolation

Each `MatildaClient` instance holds its own independent config. Multiple instances in the same process are fully isolated — constructor options are scoped to that instance.

```python title="environments.py"
staging = MatildaClient(base_url="https://staging.matilda.maincode.com/api")
prod = MatildaClient(base_url="https://matilda.maincode.com/api")

print(staging.config.base_url)  # https://staging.matilda.maincode.com/api
print(prod.config.base_url)     # https://matilda.maincode.com/api
```

## `config` (attribute)

Returns the current `MatildaConfig`.

```python
cfg = client.config
print(cfg.base_url, cfg.token)
```

## `origin` (config property)

The scheme+host of `base_url` — the origin where core-auth endpoints live. Auth flows resolve endpoints against `config.origin`, so `base_url` must be an absolute URL:

```python
client.config.origin  # e.g. "https://matilda.maincode.com"
```