Question 1

How do I create a MACAW account?

Accepted Answer

Sign up at https://console.macawsecurity.ai using OAuth (Google or GitHub). There is no separate registration form—all accounts are created via OAuth login. Your first login automatically creates a user account and an initial workspace.

Question 2

What is a workspace?

Accepted Answer

A workspace is an isolated tenant environment in MACAW. Each workspace has full multi-user, multi-workload isolation—effectively its own control plane with separate policies, agents, logs, and settings.

Each workspace:
- Has a unique slug used for routing
- Has a tier: developer (free) or paid plans
- Contains members with roles (admin or member)
- Has its own API keys, policies, and audit logs
- Is fully isolated from other workspaces

Most teams start with a single workspace. Multiple workspa

Question 3

What's the difference between Developer, Team, and Enterprise tiers?

Accepted Answer

| Feature | Developer (Free) | Team ($99/mo) | Enterprise |
|---------|------------------|---------------|------------|
| Events | 150K / 14 days | 1M / 30 days | Configurable |
| Console Users | 3 | 12 | Unlimited |
| Agents | Unlimited | Unlimited | Unlimited |
| Log Retention | 14 days | 30 days | 90+ days |
| Support | Community | Priority | Dedicated SLA |

Add-ons: +$10/100K events, +$10/user/month.

All IdP integrations (Okta, Azure AD, Auth0, Google, Keycloak) are available in all tiers.

Question 4

Where do I download the MACAW Client?

Accepted Answer

Download from the Console:
1. Log in to https://console.macawsecurity.ai
2. Navigate to the Dev Hub tab
3. Click Quick Start, select your platform and Python version
4. Click Download

The download is a .zip file containing the pre-built wheel, a pre-configured config.json with your workspace API key, the open-source adapters, examples, and a README.

Question 5

What platforms are supported?

Accepted Answer

Four platform builds are available:
- macOS (Apple Silicon) — macosx_11_0_arm64
- macOS (Intel) — macosx_10_9_x86_64
- Linux (x86_64) — manylinux_2_17_x86_64
- Windows (x64) — win_amd64

Python 3.9, 3.10, 3.11, and 3.12 are supported.

Question 6

How do I install macaw-adapters from PyPI?

Accepted Answer

bash
pip install macaw-adapters[all]

Or install specific adapters:
bash
pip install macaw-adapters[openai]
pip install macaw-adapters[anthropic]
pip install macaw-adapters[langchain]
pip install macaw-adapters[mcp]

Note: You still need macaw_client (proprietary wheel from Console) installed separately.

Question 7

What's the difference between macaw-client and macaw-adapters?

Accepted Answer

| Package | Type | Purpose |
|---------|------|---------|
| macaw_client | Proprietary (compiled wheel) | Core client library. Provides MACAWClient, agent registration, cryptographic signing, and RPC transport. Required. |
| macaw-adapters | Open Source (Apache 2.0) | Drop-in replacements for OpenAI, Anthropic, LangChain, MCP. Thin wrappers that call macaw_client. |

macaw-adapters cannot function without macaw_client installed.

Question 8

How do I verify my installation worked?

Accepted Answer

python
 Test imports
from macaw_client import MACAWClient
from macaw_adapters.openai import SecureOpenAI
print("Installation OK")

Or run the test harness included in your SDK download:
bash
python secureAI/test_harness.py

Question 9

How do I run my first example?

Accepted Answer

bash
 Set your OpenAI API key
export OPENAI_API_KEY=sk-...

Run a simple SecureOpenAI example
python -c "
from macaw_adapters.openai import SecureOpenAI

client = SecureOpenAI(app_name='my-first-app')
response = client.chat.completions.create(
    model='gpt-3.5-turbo',
    messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(response.choices[0].message.content)
"

For Anthropic:
bash
export ANTHROPIC_API_KEY=sk-ant-...

python -c "
from macaw_adapters.anthropic import SecureAnthropic

cli

Question 10

What API keys do I need to get started?

Accepted Answer

- MACAW API key: Pre-configured in your downloaded config.json (no manual entry needed)
- OpenAI API key: Required for OpenAI/LangChain-OpenAI examples (OPENAI_API_KEY)
- Anthropic API key: Required for Anthropic/LangChain-Anthropic examples (ANTHROPIC_API_KEY)

MCP examples do not require LLM API keys.

Question 11

Can I use MACAW without any LLM API keys?

Accepted Answer

Yes. You can use MCP (Model Context Protocol) features without any LLM API keys. MCP allows you to create secure tool servers that can be invoked by any MCP-compatible client.

Question 12

Where is config.json located?

Accepted Answer

Config lookup order (first match wins):
1. $MACAW_HOME/.macaw/config.json (if MACAW_HOME env var is set)
2. ./.macaw/config.json (current working directory)
3. ~/.macaw/config.json (user home directory - default)

Question 13

What does a successful first run look like?

Accepted Answer

For OpenAI drop-in example:
1. Imports succeed without errors
2. SecureOpenAI(app_name="my-app") connects to the MACAW Trust Control Plane
3. client.chat.completions.create(...) returns a response
4. Console Activity tab shows the invocation

Verify with the test harness:
bash
python test_harness.py
 Output: "✓ Connected to MACAW Trust Control Plane"

Question 14

What happens if my code can't connect to MACAW?

Accepted Answer

You'll get a connection error like "Connection refused" or "Failed to connect". Common causes:

1. Missing or invalid API key - Check ~/.macaw/config.json
2. Network connectivity - Verify you can reach api.macawsecurity.ai
3. Firewall blocking HTTPS - Ensure outbound port 443 is open

Test connectivity:
bash
curl -I https://api.macawsecurity.ai/health

Question 15

How do I invite team members?

Accepted Answer

From the Console, go to Settings tab and use the invitation system. When inviting, you can grant specific permissions:
- can_write_policies
- can_invite_users
- can_download_logs
- can_use_assistant
- can_manage_attestations

Roles are admin or member.

Question 16

What if my operation is blocked by policy?

Accepted Answer

If a request is denied, check the Console Logs tab - you'll see the policy decision with the reason for denial. Common causes:

- No policy explicitly allows the operation (default deny)
- User's claims don't match the policy requirements
- Parameter constraints violated (e.g., model not in allowed list)

The logs show exactly which policy was evaluated and why it denied the request.

Question 17

Where do I get help?

Accepted Answer

- Documentation: Check the Dev Hub in Console for guides and examples
- Community: Developer tier includes community support
- Priority support: Team tier includes priority email support
- Enterprise: Dedicated support contact with SLA

For issues, contact support@macawsecurity.com.

Getting Started