# Configuration

> Configure the shared default client, or isolate a Runner with its own client and auth.

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

---

## `configure_default_client(client)`

Installs the shared default `MatildaClient` used by the module-level convenience functions (`run`, `stream`, `stream_text`, `run_text`, `run_object`, `stream_object`) and their shared default `Runner`. Returns nothing.

```python
import os

from matilda_agent_sdk import MatildaClient, configure_default_client

configure_default_client(
    MatildaClient(
        base_url="https://matilda.maincode.com/api",
        token=os.environ["MATILDA_ACCESS_TOKEN"],
    )
)
```

The client derives its base URL, static token, and async `get_token` provider from `MatildaConfig` — see the [client SDK docs](https://maincode.com/docs/python-client-sdk-configuration) for the full field list.

## `MatildaClient`

The underlying API client, re-exported from `matilda-client`. Each `Runner` can hold its own `MatildaClient` instance for isolation, or share the module-level default.

```python
import os

from matilda_agent_sdk import MatildaClient, Runner

client = MatildaClient(
    base_url="https://matilda.maincode.com/api",
    token=os.environ["MATILDA_ACCESS_TOKEN"],
)

runner = Runner(client)
```

## `Runner`

The main agent execution class. Optionally accepts an explicit `MatildaClient` for isolation.

```python
from matilda_agent_sdk import MatildaClient, Runner

# Uses the shared default client (materialised lazily, or installed
# via configure_default_client)
default_runner = Runner()

# Uses an isolated client — independent config, auth, and token lifecycle
isolated_runner = Runner(MatildaClient(base_url="https://matilda.maincode.com/api"))
```

| Field | Type | Description |
| - | - | - |
| `client` | `MatildaClient \| None` | Optional explicit client. If omitted, the shared default is used (created on first use if none was configured). |

## Environment URLs

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

## Instance isolation

Each `Runner` holds its own `MatildaClient` (either explicit or the shared default). The `auth`, `files`, `conversations`, and `feedback` resources resolve their client lazily, so a client installed via `configure_default_client()` is picked up correctly.

```python
from matilda_agent_sdk import MatildaClient, Runner

runner_a = Runner(MatildaClient(base_url="https://matilda.maincode.com/api"))
runner_b = Runner(MatildaClient(base_url="https://matilda.maincode.com/api"))

# Each runner is fully isolated — independent auth, config, and token lifecycle
await runner_a.auth.login_with_device_flow(client_id="matilda-code")
await runner_b.auth.login_with_browser(client_id="matilda-code")
```

## Other configuration utilities

| Export | Description |
| - | - |
| `MatildaConfig` | Client configuration dataclass (re-exported from `matilda-client`). |
| `MATILDA_API_VERSION_HEADER` / `MATILDA_CURRENT_API_VERSION` | API version constants, importable from `matilda_client`. |