mountAgentControllerOnMastra()

beta

Breaking changes may occur without a major version bump until the API is stable.

The mountAgentControllerOnMastra() function builds the Mastra Code agent controller (the coding agent behind Mastra Code, with its modes, tools, memory, and thread management) and registers it on a server-owned Mastra instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned AgentController.

To construct the Mastra instance yourself (for example in a deployable entry file), use prepareAgentControllerMount() from the same package, which returns the constructor args plus a finalize() callback.

Usage example

src/mastra/index.ts

import { mountAgentControllerOnMastra } from '@mastra/code-sdk'

const { mastra, controller } = await mountAgentControllerOnMastra({
  cwd: process.cwd(),
})

// Each client drives its own session
const session = await controller.createSession({ resourceId: 'user-123' })

Commit attribution

Use coAuthor to set the Co-Authored-By trailer in coding-agent commit guidance:

src/mastra/index.ts

const { mastra, controller } = await mountAgentControllerOnMastra({
  cwd: process.cwd(),
  coAuthor: {
    name: 'my-coding-app',
    email: 'my-coding-app@example.com',
  },
})

Both fields are optional. An omitted field uses the SDK default: mastra-platform[bot] for the name and 284800079+mastra-platform[bot]@users.noreply.github.com for the email.

The mastracode terminal app sets its name to mastracode, and Factory sets its name to mastra-platform[bot]. Both use the same default email, so GitHub resolves their trailers to the same bot account while the raw commit message retains the app name.

Pass an existing mastra to mount the controller onto a Mastra instance that already hosts other primitives:

import { Mastra } from '@mastra/core/mastra'
import { mountAgentControllerOnMastra } from '@mastra/code-sdk'

const mastra = new Mastra({/* ... */})

const { controller } = await mountAgentControllerOnMastra({ mastra })

Parameters

cwd?:

string

= process.cwd()

Working directory for project detection.

coAuthor?:

{ name?: string; email?: string }

Commit co-author identity included in coding-agent commit guidance. Omitted fields use the SDK defaults.

mastra?:

Mastra

Existing Mastra instance to mount onto. When omitted, a Mastra is created that owns the controller storage.

controllerId?:

string

Id under which the controller is registered on the Mastra instance.

modes?:

AgentControllerMode[]

= build/plan/fast

Override agent modes (model ids, colors, which modes exist).

subagents?:

AgentControllerSubagent[]

= explore/plan/execute

Override or extend subagent definitions.

extraTools?:

Record<string, ToolAction> | (ctx) => Record<string, ToolAction>

Extra tools merged into the dynamic tool set.

postToolObserver?:

(context: ToolAfterHookContext) => void | Promise<void>

Observes completed tool calls without replacing the tool or changing hook-manager behavior. Observer errors are logged and do not fail successful tool calls.

inputProcessors?:

InputProcessor[]

Stateless input processors prepended before Mastra Code's mandatory safety and compatibility processors. Custom processors extend the pipeline but can't replace the built-in processors.

disabledTools?:

string[]

Tools removed from the dynamic tool set before exposure to the model.

storage?:

StorageConfig

Custom storage config instead of the auto-detected default.

workspace?:

AgentControllerConfig["workspace"]

= local filesystem + local sandbox based on the detected project

Override the workspace.

configDir?:

string

= '.mastracode'

Override the config directory name used for all project-level and global config paths (MCP, hooks, commands, database, skills, agent instructions).

mcpServers?:

Record<string, McpServerConfig>

Programmatic MCP server configurations, merged with (and overriding) file-based configs.

buildApiRoutes?:

(deps: { controller, authStorage }) => ApiRoute[]

Additional API routes registered on the constructed Mastra. Ignored when mastra is provided.

buildServerConfig?:

(deps: { controller, authStorage }) => ServerConfig

Additional server config (middleware, CORS) folded onto the constructed Mastra. Ignored when mastra is provided.

Returns

mastra:

Mastra

The Mastra instance the controller is mounted on (created or passed in).

controller:

AgentController

The initialized Mastra Code agent controller. Create sessions with controller.createSession().

authStorage:

AuthStorage

Credential storage used by the built-in model gateway.

Nested controllers in plugins

A plugin that boots another controller in the same process must borrow the host's storage instead of opening the same database files with its own native SQLite library.

context.getStorage()

The optional accessor on MastraCodePluginContext returns the host's storage (MastraCompositeStore), storageBackend ('libsql' | 'pg'), and optional vector (MastraVector). Call it when the tool runs, then pass the returned object to bootLocalAgentController():

import { bootLocalAgentController } from '@mastra/code-sdk'
import type { MastraCodePluginContext } from '@mastra/code-sdk/plugin'

async function bootNestedController(context: MastraCodePluginContext) {
  const sharedStorage = context.getStorage?.()
  if (!sharedStorage) {
    throw new Error('This plugin requires host-provided shared storage.')
  }
  return bootLocalAgentController({ cwd: context.cwd, ...sharedStorage })
}

The host owns these instances. Stop the nested controller's workers and destroy its controller when finished, but don't close the borrowed stores or invoke its storage-maintenance methods. If the accessor is unavailable on an older host, don't fall back to opening the same database files.

Related

• AgentController class
• Session class