OpenBox Mastra SDK

@openbox-ai/openbox-mastra-sdk adds OpenBox governance, approvals, guardrails, and OpenTelemetry-backed operational telemetry to Mastra applications.

Use it when you need to:

• evaluate tools, workflow steps, workflows, and agents against OpenBox policy
• enforce approval flows from OpenBox verdicts
• apply input and output guardrails
• attach HTTP, database, file, and traced-function telemetry to governed runs
• install the integration once and keep future Mastra registrations governed

Requirements

• Node.js >=24.10.0
• @mastra/core ^1.8.0
• an OpenBox Core deployment reachable from the Mastra runtime
• an ESM-capable runtime and build pipeline

Installation

The SDK is published on npm as @openbox-ai/openbox-mastra-sdk.

npm install @openbox-ai/openbox-mastra-sdk @mastra/core

Required environment variables:

export OPENBOX_URL="https://your-openbox-core.example"
export OPENBOX_API_KEY="obx_live_your_key"

For agents that require DID signing, OpenBox also returns a DID and private key during agent registration or identity rotation. Set both values together:

export OPENBOX_AGENT_DID="did:aip:your-agent-did"
export OPENBOX_AGENT_PRIVATE_KEY="base64_raw_ed25519_seed"

Optional but commonly used:

export OPENBOX_GOVERNANCE_POLICY="fail_open"
export OPENBOX_DEBUG="false"

Quick Start

import { Mastra } from "@mastra/core/mastra";
import {
  getOpenBoxRuntime,
  withOpenBox
} from "@openbox-ai/openbox-mastra-sdk";

const mastra = new Mastra({
  agents: {
    // your agents
  },
  tools: {
    // your tools
  },
  workflows: {
    // your workflows
  }
});

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

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

withOpenBox() is the recommended production entrypoint. It:

1. parses and validates SDK configuration
2. validates the API key unless validate: false is set
3. creates the OpenBox client and span processor
4. installs process-wide telemetry
5. wraps existing Mastra tools, workflows, and agents
6. patches future addTool(), addWorkflow(), and addAgent() calls

Reference Demo

For a runnable reference application, use the Mastra coding-agent POC:

• GitHub: https://github.com/OpenBox-AI/poc-mastra-coding-agent/tree/dev

The POC installs @openbox-ai/openbox-mastra-sdk from npm. You do not need a sibling checkout of this repository to run it.

Bundled Example

If you want to validate the SDK locally before wiring a real OpenBox environment, this repository also includes a bundled quickstart example:

npm run example:quickstart

This example runs against a local mock OpenBox server and demonstrates:

• a governed workflow
• a suspended approval and resume path
• a governed tool execution
• a wrapped summary agent

Use the npm package for real integrations. Clone this repository only when you want to run the bundled example or work on the SDK itself.

Runtime Model

The SDK emits three categories of OpenBox payloads:

• boundary workflow events: WorkflowStarted, WorkflowCompleted, WorkflowFailed
• boundary activity events: ActivityStarted, ActivityCompleted
• signal events: SignalReceived for workflow resume, agent user_input, agent resume, and agent agent_output

It also captures operational spans for:

• HTTP requests
• supported database libraries
• file operations when file instrumentation is enabled
• custom functions wrapped with traced()

Important production behavior:

• agent-only LLM activity is represented as telemetry spans, not as standalone business activities
• agent prompts are emitted as SignalReceived(user_input), not as tool activities
• the SDK ignores its own OpenBox API URL during telemetry setup to avoid feedback loops

Configuration Highlights

Most applications only need a small part of the config surface:

| Option | Default | Use it to | | --- | --- | --- | | apiUrl | required | point the SDK at OpenBox Core | | apiKey | required | authenticate governance and approval calls | | agentDid | unset | identify the agent for DID-signed OpenBox requests | | agentPrivateKey | unset | sign OpenBox requests for agents with signing required | | validate | true | fail fast on invalid credentials or insecure URL setup | | onApiError | "fail_open" | decide whether OpenBox outages should halt execution | | hitlEnabled | true | enable approval suspension or polling flows | | httpCapture | true | attach text HTTP bodies and headers to governance-relevant telemetry | | instrumentDatabases | true | capture supported database activity | | instrumentFileIo | false | enable file operation telemetry when required | | sendStartEvent | true | emit WorkflowStarted | | sendActivityStartEvent | true | emit ActivityStarted | | skipActivityTypes | ["send_governance_event"] | suppress selected activity types entirely | | skipSignals | empty | suppress selected signal names | | maxEvaluatePayloadBytes | 256000 | cap payload size before compact fallback logic applies |

See docs/configuration.md for the complete surface.

Production Guidance

• Keep validate enabled outside tests and local mocks.
• Use HTTPS for all non-localhost OpenBox endpoints.
• Store OPENBOX_AGENT_PRIVATE_KEY as a secret and never share it between agents.
• Decide explicitly between fail_open and fail_closed before deployment.
• Treat hook-triggered telemetry as internal operational data unless your policy intentionally governs it.
• Keep instrumentFileIo disabled until you have a concrete file-governance requirement.
• Initialize telemetry once per process and shut it down on process exit.

Documentation

• docs/README.md: documentation index and reading order
• docs/installation.md: installation, startup, and shutdown
• docs/configuration.md: configuration surface, env vars, and defaults
• docs/integration-patterns.md: withOpenBox() and manual integration patterns
• docs/architecture.md: runtime architecture and data flow
• docs/event-model.md: event types, payload shape, signals, and activity semantics
• docs/telemetry.md: HTTP, database, file, and traced-function capture
• docs/approvals-and-guardrails.md: verdict enforcement, approvals, and guardrails
• docs/security-and-privacy.md: transport, capture boundaries, and hardening guidance
• docs/troubleshooting.md: common failures and diagnostics
• docs/api-reference.md: public API summary

Public API Summary

Top-level exports include:

• withOpenBox() and getOpenBoxRuntime()
• wrapTool(), wrapWorkflow(), and wrapAgent()
• OpenBoxClient
• parseOpenBoxConfig() and initializeOpenBox()
• setupOpenBoxOpenTelemetry() and traced()
• OpenBoxSpanProcessor
• verdict, guardrail, workflow event, and error types

See docs/api-reference.md for the full reference.