Mastra SDK (TypeScript)
The OpenBox Mastra SDK connects a Mastra runtime to OpenBox. It governs tools, workflow steps, workflows, and agent runs while attaching operational telemetry that operators can inspect in the dashboard.
Published package: @openbox-ai/openbox-mastra-sdk
Runnable reference application:
| Guide | Description |
|---|---|
| Integration Walkthrough | End-to-end guide for wiring withOpenBox(), manual wrappers, and telemetry into a Mastra service |
| Configuration | Environment variables, runtime options, defaults, and production guidance |
| Error Handling | Runtime errors, approval outcomes, guardrail failures, and startup validation issues |
| Event Model | Understand workflows, activities, signals, and how Mastra runs appear in OpenBox |
| Approvals and Guardrails | How verdicts are enforced and how to test live guardrails correctly |
| Telemetry | HTTP, database, file, and traced-function capture behavior |
| Troubleshooting | Diagnose startup, policy, approvals, telemetry, and UI interpretation issues |
The SDK's job is to connect a Mastra runtime to OpenBox. Trust policy, approvals, guardrails, dashboards, and operator workflows live on the OpenBox platform, not inside the SDK.
Philosophy
The integration is intentionally minimal:
- One standard bootstrap path with
withOpenBox() - No rewrite of existing agent, tool, or workflow logic
- Automatic governance at Mastra runtime boundaries
- Automatic telemetry capture through OpenTelemetry
Recommended Entry Point
For most services, use withOpenBox():
import { withOpenBox } from "@openbox-ai/openbox-mastra-sdk";
await withOpenBox(mastra, {
apiKey: process.env.OPENBOX_API_KEY,
apiUrl: process.env.OPENBOX_URL
});
It validates configuration, creates the OpenBox runtime, installs telemetry, wraps existing registrations, and keeps future Mastra registrations governed.
Public API Summary
Most integrations only need these exports:
withOpenBox()getOpenBoxRuntime()wrapTool()wrapWorkflow()wrapAgent()setupOpenBoxOpenTelemetry()traced()
What The SDK Captures
OpenBox receives:
Workflow Boundaries
WorkflowStartedWorkflowCompletedWorkflowFailed
Activity Boundaries
ActivityStartedActivityCompleted
These apply to:
- wrapped tools
- wrapped non-tool workflow steps
Signals
SignalReceived(user_input)SignalReceived(resume)SignalReceived(agent_output)
Operational Telemetry
- HTTP requests
- supported database activity
- file operations when enabled
- custom traced functions
Supported Runtime Conditions
| Requirement | Value |
|---|---|
| Node.js | >=24.10.0 |
| Mastra | @mastra/core ^1.8.0 |
| Module format | ESM |
| OpenBox Core | reachable over HTTPS except localhost development |
Next Steps
- Start with the Integration Walkthrough.
- Configure production behavior in Configuration.
- Read Event Model before writing policy or guardrails.