Connecting the macOS Collector

Connect the CloudZero macOS Collector to bring AI usage from the tools your developers already run into a unified view of all your cloud and AI spend. The Collector is a menu-bar app that captures AI provider calls made from a Mac, then reports model, token, and cost metadata to CloudZero. Once connected, you organize that spend alongside your other costs using Dimensions that matter to your business, such as team, product, or environment.

This guide covers installing the Collector on a single Mac and verifying data flows to CloudZero. For an org-wide rollout through an MDM, see Deploying org-wide with MDM.

How it works

The Collector intercepts AI provider API calls at the macOS network layer, so there is no per-tool configuration. Any supported AI tool on the machine is captured automatically. The original requests and responses pass through unchanged, so your AI tools behave exactly as before. If the Collector ever stops, traffic keeps flowing uninterrupted (fail-open).

The Collector manages its own ingest endpoint, so there is no OTLP endpoint or gateway URL for you to set. You create a CloudZero API key, enter it in the app, and the Collector handles the rest. Activity appears in AI Signals within seconds of usage, and full cost exploration in the Explorer follows within about 24 hours.

CloudZero never reads or stores prompt or response content. Only model, token, timing, and cost metadata are ingested.

Provider coverage

The Collector captures the following today:

Provider	What is captured
Claude Code	Model, token counts (including cache), cost, organization ID
Claude Cowork	Model, token counts (including cache), cost, organization ID
claude.ai web and desktop	Byte-level usage, conversation and session correlation, model, subscription quota signals
Vertex AI	Model, token counts, cost

ℹ️
Usage from claude.ai web and desktop is measured differently from the API-based tools. Cost is allocated proportionally from byte-level usage rather than exact token counts, so these numbers are directionally accurate but do not match API-based telemetry one-for-one. If your team will be comparing the two, set that expectation up front.

OpenAI, Azure OpenAI, and Amazon Bedrock are not yet validated on the Collector. If you use these providers, talk to your account manager about current coverage.

ℹ️
This integration does not use the Create Connection flow in Settings > Cloud Connections. You connect it by installing the Collector and entering a CloudZero API key, as described below. Confirm it is working in AI Signals once data flows.

What you need

A CloudZero user with API key access
A Mac running macOS 14 (Sonoma) or later, with an admin account
For Anthropic and claude.ai attribution: a claude.ai account with an active session

⚠️
If your organization runs Zscaler, Netskope, or similar TLS inspection, confirm before you install. These tools inspect TLS traffic the same way the Collector does, and running both in the same path conflicts. There is no clean workaround today, so coordinate with your IT team and your account manager before deploying.

Step 1: Create a CloudZero API key

In CloudZero, go to Settings > API Keys.
Create a new API key.
Under Scopes, open the Ai-Telemetry-Ingest category and select ingest-cz-telemetry-v1. You can type telemetry in the scope search box to find it.
Copy the key value and store it securely. You enter it in the app in Step 5. Treat it like any other secret.

ℹ️
The scope matters. Without the ingest-cz-telemetry-v1 scope, the Collector appears to work but its events are silently rejected. If your data never appears in CloudZero, check this first.

Step 2: Install the Collector

Download the CloudZero .pkg. Your account manager shares the download link.
Double-click the .pkg in Finder and follow the installer wizard.
When macOS prompts for your admin password, enter it.

The .pkg is signed and notarized, so macOS Gatekeeper passes it without any configuration changes. The installer handles certificate setup, the Network Extension, and starting the app. When the wizard finishes, the app is already running.

Step 3: Approve the Network Extension

When prompted, click Open System Settings. Do not click OK. This takes you to the Network Extensions pane, where you enable the toggle for CloudZero and click Done.

If the prompt does not appear, open /Applications/CloudZero.app to trigger the approval flow.

Step 4: Sign in to claude.ai

This step applies only if your team uses Anthropic or claude.ai.

Click Sign in to Claude.ai and authenticate in the browser. Select the correct organization and project, then click Done. This connects the Collector to your Anthropic account so usage attributes correctly.

Step 5: Set identity

In the app, go to Settings > Identity and enter the user's work email and department. This is what turns raw machine data into people and teams in CloudZero.

⚠️
Do not skip this step. The machine hostname is always recorded, but without identity the usage attributes only to that hostname (for example, alice-mbp.local) instead of to a person and team (for example, Alice Smith / Engineering). You can set it later in Settings > Identity, but it is easiest to do it now.

Step 6: Enter the CloudZero API key

Enter the API key from Step 1 in the app and click Save. It is stored securely in the macOS Keychain, not on disk. The Collector begins reporting telemetry once the key is saved.

Step 7: Verify in the Debug tab

Open the CloudZero menu-bar app, go to Settings > Debug, and confirm all indicators are green:

Env Cleanup
Proxy Runtime
Cert Generate
Cert Install
Cert Trust
CA Bundle
Database
Proxy
Shipper
Network Extension

If any indicator is red, see Troubleshooting.

Step 8: Restart your terminals and AI tools

⚠️
Restart any terminal that was open before or during install. Terminals opened before install do not pick up the Collector's certificate settings, and command-line tools like Claude Code throw SSL errors until you restart. Quit the terminal completely with Cmd+Q (do not just close the window), then reopen it.

The Collector only captures new connections, so also restart any AI tools that were already running during install. That way their traffic is captured.

Step 9: Send a test call and verify

Make an AI call in Claude Code or Claude Cowork.
Within a few seconds, the CloudZero menu-bar app shows token and cost activity.
Open CloudZero and watch the AI Signals view for the same activity.

Activity in the AI Signals view confirms the Collector is working. The Explorer follows within about 24 hours.

What to expect

After you connect, Collector activity works like any other cost data in CloudZero:

AI Signals: normalized inference events as they arrive, showing model, token counts, and timing. Events appear within seconds of usage.
Explorer: the downstream exploration experience, breaking down cost by model over time. This data is processed downstream of ingest, so allow about 24 hours after activity for it to appear here.

From there, you can explore your AI costs in the Explorer, organize them by team or product using Dimensions, track trends in Dashboards, set Budgets, or ask questions in the AI Hub.

Deploying org-wide with MDM

To roll the Collector out to many Macs at once, deploy it through your MDM (Jamf, Kandji, Intune, or similar). This is a zero-touch, profile-based setup that pushes a set of configuration profiles ahead of the installer package, covering Network Extension approval, proxy activation, and optionally pre-populated identity and API key.

For the full profile-by-profile steps, see Deploying the CloudZero AI Collector With MDM.

ℹ️
One certificate-trust approval (a single keychain prompt per device) cannot be suppressed today, even under MDM, so users still see it once at first launch. If you are planning a broader rollout, loop in your account manager to help you sequence it.

Data privacy

The Collector is built so prompt and response content never reaches CloudZero. Only per-request metadata does.

No prompt or response content is sent to CloudZero. Only per-request metadata (model, token counts, cost, latency) leaves the device.
API keys are redacted. Only the first 16 and last 4 characters are retained; the full key is never stored or transmitted.
The signing certificate is generated uniquely per machine, and its private key never leaves the device.
If the local proxy stops for any reason, AI traffic passes through uninterrupted (fail-open).

Troubleshooting

If data is not appearing in the AI Signals view after confirmed usage, work through these in order.

API key entered and correct? Open Settings > API Key. If it is empty or wrong, create a new key (Step 1) and enter it.
Missing scope. The key must have the ingest-cz-telemetry-v1 scope. Without it the Collector appears to work but events are silently rejected.
Certificate trust dismissed? If the trust prompt was dismissed during setup, open the app and complete the first-launch steps again.
Network Extension enabled? Go to System Settings > General > Login Items & Extensions > Network Extensions. CloudZero should be listed and toggled on.
Terminal SSL errors or no data from command-line tools? Terminals opened before install do not have the Collector's certificate settings. Quit the terminal with Cmd+Q and reopen it. The same can happen after a reboot.
Restarted the app or the machine? Repeated installs can leave the Network Extension in a stale state. A full restart is the fastest fix when everything above looks correct but traffic still is not captured.
Events showing $0.00 cost? Token counts are still correct; only the cost for that specific model could not be resolved. This is rare. Note the model name and pass it to your account manager so the rate can be added.

To remove the Collector, open the menu-bar app and use the built-in uninstall wizard.

ℹ️
Have questions or feedback? Reach out to your account manager.