System Architecture
MACAW implements a cloud-native, zero-trust architecture. The Control Plane runs as a managed service, while lightweight SDKs on your endpoints handle cryptographic signing and policy enforcement. All configuration happens through the Console.
High-Level Overview
┌─────────────────────────────────────────────────────────────────────┐
│ YOUR ENDPOINTS (Dev/DevOps) │
│ ┌──────────────────┐ ┌─────────────────────────────────────────┐│
│ │ macaw-client SDK │ │ macaw-adapters ││
│ │ (from Console) │ │ SecureOpenAI, SecureAnthropic, ││
│ │ │ │ SecureLangChain, SecureMCP ││
│ └────────┬─────────┘ └──────────────────┬──────────────────────┘│
│ │ │ │
│ └──────────────┬───────────────────┘ │
└──────────────────────────┼───────────────────────────────────────────┘
│ HTTPS (signed requests)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ MACAW CLOUD CONTROL PLANE │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Registry │ │ Policy │ │ Identity │ │ Audit │ │Attestat- │ │
│ │ Service │ │ Store │ │ Bridge │ │ Logger │ │ion Svc │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
▲
│ Web UI
┌──────────────────────────┼───────────────────────────────────────────┐
│ CONSOLE (Admin) │
│ Identity Setup │ Policies │ Attestations │ Logs & Traces │ Team │
└─────────────────────────────────────────────────────────────────────┘Core Components
macaw-client SDK
Lightweight Python SDK downloaded from the Console. Connects your application to the Control Plane with a pre-configured API key. Handles cryptographic signing, policy enforcement, and audit logging.
Adapters (SDK Layer)
Drop-in replacements for AI SDKs. Change one import, keep all your code. Each adapter wraps MACAWClient internally to add security transparently.
Control Plane (Cloud Services)
Managed cloud services that handle agent registration, policy storage, identity resolution, and audit collection. Your SDK connects to these services automatically.
Console (Web UI)
Web interface for administrators. All configuration, policy management, and observability happens here. Download the SDK, configure identity providers, create policies, view logs.
Request Flow
Application Request
Your app calls SecureOpenAI (or MACAWClient directly) with optional JWT token from your identity provider.
SDK Signs Request
The SDK creates a cryptographically signed invocation with the request parameters and security context.
Control Plane Validates
Identity Bridge converts JWT claims into security context. Policy Store evaluates MAPL policies and may adjust parameters.
Execution & Audit
If policy permits, request executes. Full audit trail recorded with signatures. View results in Console.
Control Plane Services
The Control Plane consists of several services that work together. All communication is encrypted and authenticated.
| Service | Responsibility | State |
|---|---|---|
| Registry Service | Agent registration, key management, capability discovery | Per-tenant agent database |
| Identity Bridge | JWT validation, claims mapping, security context creation | Stateless (JWT-based) |
| Policy Store | MAPL policy storage, inheritance resolution, enforcement | Policy database with history |
| Audit Logger | Event collection, signature verification, OTEL export | Append-only audit log |
| Attestation Service | External approvals (human, agent, or system), attestation lifecycle | Attestation database with lifecycle |
Two Interfaces
For Developers
Use the SDK and adapters in your code. Download from Console, install with pip, import and use.
- - macaw-client SDK (from Console)
- - macaw-adapters (from PyPI)
- - Pre-configured with your API key
For Administrators
Use the Console for all configuration and monitoring. No CLI tools needed.
- - Configure identity providers
- - Create and manage policies
- - View logs, traces, attestations
- - Manage team and permissions