# Configuration

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

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

---

## `configureClient(options)`

Configures the default `MatildaCore` singleton used by `defaultRunner` and the convenience functions (`run`, `stream`, `streamText`, `runText`). Returns nothing.

```ts
import { configureClient } from '@maincode-ai/matilda-agent-sdk';

configureClient({
  baseUrl: 'https://matilda.maincode.com/api',
  getToken: async () => myAccessToken,
});
```

### Options

Extends `ClientConfig`. All fields are optional except `baseUrl`.

| Field | Type | Description |
| - | - | - |
| `baseUrl` | `string` | The Matilda API base URL. Must be absolute for auth flows. Defaults to '/api'. |
| `accessToken` | `string` | A static access token. Use for quick testing only — prefer managed auth. |
| `getToken` | `GetToken` | Dynamic token provider. Called on every request. The SDK's TokenManager implements this. |
| `apiVersion` | `string \| null` | API version sent via the X-Matilda-API-Version header. Omit to use the current version. |
| `urlPolicy` | `TrustedApiBaseUrlPolicy` | URL validation policy for trustApiBaseUrl(). |
| `getCsrfToken` | `() => string \| null` | CSRF token provider for web BFF cookie auth. |

## `MatildaCore`

The underlying API client. The agent SDK re-exports it from `@matilda/api-client`. Each `Runner` can hold its own `MatildaCore` instance for isolation, or share the process-wide default.

```ts
import { MatildaCore, Runner } from '@maincode-ai/matilda-agent-sdk';

const core = new MatildaCore({
  baseUrl: 'https://matilda.maincode.com/api',
  accessToken: process.env.MATILDA_ACCESS_TOKEN!,
});

const runner = new Runner({ core });
```

## `Runner`

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

```ts
import { Runner, MatildaCore } from '@maincode-ai/matilda-agent-sdk';

// Uses the default core singleton (configured via configureClient)
const defaultRunner = new Runner();

// Uses an isolated core — independent config, auth, and token lifecycle
const isolatedRunner = new Runner({
  core: new MatildaCore({ baseUrl: 'https://matilda.maincode.com/api' }),
});
```

| Field | Type | Description |
| - | - | - |
| `core` | `MatildaCore` | Optional explicit core. If omitted, the default singleton is used. |

## Environment URLs

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

## Instance isolation

Each `Runner` holds its own `MatildaCore` (either explicit or the default singleton). Resources (`auth`, `files`, `conversations`, `feedback`) resolve their core lazily, so `configureClient()` replacing the default singleton is picked up correctly.

```ts
import { Runner, MatildaCore, configureClient } from '@maincode-ai/matilda-agent-sdk';

const runnerA = new Runner({
  core: new MatildaCore({ baseUrl: 'https://matilda.maincode.com/api' }),
});
const runnerB = new Runner({
  core: new MatildaCore({ baseUrl: 'https://matilda.maincode.com/api' }),
});

// Each runner is fully isolated — independent auth, config, and token lifecycle
await runnerA.auth.loginWithDeviceFlow({ clientId: 'matilda-code' });
await runnerB.auth.loginWithBrowser({ clientId: 'matilda-code' });
```

## Other re-exported configuration utilities

| Export | Description |
| - | - |
| `configureClient(options)` | Configure the default `MatildaCore` singleton. |
| `getClientConfig()` | Get the current default core's config. |
| `getDefaultCore()` | Get the default `MatildaCore` singleton. |
| `trustApiBaseUrl(rawUrl, policy?)` | Validate and brand a URL as a trusted API base URL. |
| `MATILDA_API_VERSION_HEADER` | The API version header name. |
| `MATILDA_CURRENT_API_VERSION` | The current API version string. |