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,
agentDid: process.env.OPENBOX_AGENT_DID,
agentPrivateKey: process.env.OPENBOX_AGENT_PRIVATE_KEY
});
It validates configuration, creates the OpenBox runtime, installs telemetry, wraps existing registrations, and keeps future Mastra registrations governed.
Newly created OpenBox agents require DID signing by default. Configure agentDid and agentPrivateKey together unless Require signing is disabled for the registered agent, and store the private key as a per-agent secret.
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.