Last updated on Mar 30, 2026

Tags:

• Getting Started
• Mastra
• TypeScript

Options

Open in ChatGPTAsk ChatGPT about this page↗Open in ClaudeAsk Claude about this page↗

Getting Started with Mastra

OpenBox integrates with Mastra by wrapping the Mastra runtime during startup. Your agents, tools, and workflows stay in place while OpenBox adds governance, approvals, guardrails, and operational telemetry.

One Bootstrap Change

Mastra

src/mastra/index.ts

import { Mastra } from "@mastra/core/mastra";
import { myAgent } from "./agents/my-agent";
import { myWorkflow } from "./workflows/my-workflow";
import { myTool } from "./tools/my-tool";

export const mastra = new Mastra({
  agents: { myAgent },
  workflows: { myWorkflow },
  tools: { myTool }
});

OpenBox

src/mastra/index.ts

import { Mastra } from "@mastra/core/mastra";
import { getOpenBoxRuntime, withOpenBox } from "@openbox-ai/openbox-mastra-sdk";
import { myAgent } from "./agents/my-agent";
import { myWorkflow } from "./workflows/my-workflow";
import { myTool } from "./tools/my-tool";

const mastra = new Mastra({
  agents: { myAgent },
  workflows: { myWorkflow },
  tools: { myTool }
});

export const governedMastra = await withOpenBox(mastra, {
  apiKey: process.env.OPENBOX_API_KEY,
  apiUrl: process.env.OPENBOX_URL
});

process.on("SIGTERM", async () => {
  await getOpenBoxRuntime(governedMastra)?.shutdown();
});

Choose Your Path

Mastra 101

Get the Mastra concepts that matter for OpenBox before you wire governance into a real service.

Run the Demo

Run the public Mastra coding-agent POC and see OpenBox govern sandbox creation, file operations, and shell-command activity.

Wrap an Existing Agent

Add OpenBox to an existing Mastra codebase without rewriting your agents, tools, or workflows.

What OpenBox Captures

From a single integration point, OpenBox captures:

• Workflow lifecycle events for workflows and agent runs
• Activity lifecycle events for tools and governed non-tool workflow steps
• Agent signals such as user_input, resume, and agent_output
• HTTP, database, file, and traced-function telemetry
• Governance decisions, approvals, and guardrail outcomes

What To Expect In The UI

After integration, OpenBox gives you:

• A run timeline for workflows, tools, and agents
• Policy and guardrail decisions on governed boundaries
• Session replay with runtime context
• Model and token usage for agent runs
• Tool health metrics for agents that actually execute tools

Next Steps

1. Read Mastra 101 if you want the conceptual model first.
2. Use Run the Demo for the runnable coding-agent POC.
3. Use Wrap an Existing Agent if you already have Mastra in production.
4. Continue to the Mastra Developer Guide for configuration, event semantics, telemetry, and troubleshooting.