Agent SDK · Start here

Configuration.

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

`configureClient(options)`

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

TypeScript

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.

TypeScript

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.

TypeScript

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.

TypeScript

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.