control-zero (Node.js)

AI agent governance SDK for Node.js.

Install

npm install control-zero

Quick Start (TypeScript)

import { ControlZeroClient } from 'control-zero';

const cz = new ControlZeroClient({ apiKey: 'cz_test_yourkey' });

await cz.logToolCall({
  agentId: 'my-agent',
  tool: 'github',
  method: 'list_issues',
  params: { repo: 'myorg/myrepo' },
});

Full Client API

import { ControlZeroClient } from 'control-zero';

// Initialize with your API key
const client = new ControlZeroClient({
  apiKey: 'cz_live_xxx',
});

// This fetches config, secrets, and policies from Control Zero
await client.initialize();

// Call MCP tools - secrets are injected automatically!
const result = await client.callTool('github', 'list_issues', { repo: 'acme/app' });

// Close when done (flushes logs)
await client.close();

Features

Automatic Secret Injection

Secrets configured in the Control Zero dashboard are automatically:

1. Fetched encrypted from the server
2. Decrypted in memory
3. Injected into your MCP calls
4. Wiped from memory on session end

// No need to manage secrets in your code!
// GitHub PAT is automatically injected
const result = await client.callTool('github', 'create_issue', {
  repo: 'acme/app',
  title: 'Bug report',
});

Policy Enforcement

Policies defined in the dashboard are enforced locally:

import { ControlZeroClient, PolicyDeniedError } from 'control-zero';

try {
  const result = await client.callTool('stripe', 'create_charge', {...});
} catch (error) {
  if (error instanceof PolicyDeniedError) {
    console.log(`Denied: ${error.decision.reason}`);
  }
}

Audit Logging

All tool calls are automatically logged for compliance:

• Timestamp, tool, method
• Latency and status
• Policy decisions
• Errors (without sensitive data)

Logs are batched and sent asynchronously to avoid impacting performance.

Configuration

const client = new ControlZeroClient({
  apiKey: 'cz_live_xxx', // Required
  agentName: 'marketing-bot', // Optional, for logging
  baseUrl: 'https://api.controlzero.ai', // Or self-hosted
});

Deployment Modes

Control Zero supports three deployment modes for different environments:

Cloud Mode (Default)

Policies are fetched from the API on initialization. Best for cloud deployments with internet connectivity.

const client = new ControlZeroClient({
  apiKey: 'cz_live_xxx',
  // Policies automatically fetched from API
});

Hybrid Mode (Recommended for Production)

Policies are cached locally and refreshed in the background. Works offline with cached policies.

const client = new ControlZeroClient({
  apiKey: 'cz_live_xxx',
  policyMode: 'hybrid',
  policyCachePath: './cache/policies.json', // Optional
  policyRefreshInterval: 300000, // Refresh every 5 minutes (in ms)
});

Local Mode (Air-Gapped)

Policies are loaded from a local file. No network calls for policy fetching.

const client = new ControlZeroClient({
  apiKey: 'cz_live_xxx',
  policyMode: 'local',
  policyPath: './policies.czpolicy',
});

Download policy bundles from your project dashboard or via API:

curl -H "Authorization: Bearer $API_KEY" \
  https://api.controlzero.ai/api/projects/{projectID}/policies/download \
  -o policies.czpolicy

See deployment modes documentation for detailed comparison and migration guides.

API Key Types

• cz_live_* - Production keys (real secrets, real logging)
• cz_test_* - Test keys (mock responses, test logging)

Security

• Secrets are held in memory only, never written to disk
• Memory is securely wiped on session end
• All communication is encrypted (TLS)
• Policies are enforced locally for low latency

Development

Running Tests

# Install dependencies
npm install

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Building

# Build TypeScript
npm run build

# Type checking
npm run typecheck

Examples

See the examples/ directory for complete usage examples:

• slack-bot.ts - Secure Slack messaging with channel restrictions
• database-agent.ts - PostgreSQL with read-only policies
• analytics-agent.ts - Analytics database queries with governance
• github-agent.ts - GitHub operations with branch protection
• multi-tool-agent.ts - Complete multi-tool workflow

License

Proprietary - Control Zero, Inc.