Skip to main content

mountAgentControllerOnMastra()

beta

The @mastra/code-sdk package is experimental and subject to breaking changes in minor versions.

The mountAgentControllerOnMastra() function builds the Mastra Code agent controller — the coding agent behind the mastracode CLI, 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
Direct link to 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' })

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
Direct link to Parameters

cwd?:

string
= process.cwd()
Working directory for project detection.

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.

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
Direct link to 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.
On this page