@veridex/agents-control-plane

Persistent control-plane service and client for operating Veridex agents in multi-tenant, policy-bound, approval-heavy, and audit-sensitive environments.

Status

@veridex/agents-control-plane now includes a real service, a remote client, file-backed and Postgres-backed persistence, and deployment surfaces for managed environments. It is no longer just an SDK sketch, but it is still early enough that operational feedback and contribution are valuable.

What This Package Does

Use this package when you need:

• tenant isolation
• policy pack management
• approval workflows and escalation
• trace ingestion and retention
• evidence bundle and audit export
• remote authenticated APIs
• deployable control-plane infrastructure
• shared Postgres-backed persistence for multiple service instances

Installation

npm install @veridex/agents-control-plane @veridex/agents

Core Exports

Service and API

• ControlPlaneService
• createControlPlaneApp
• startControlPlaneServer
• RemoteControlPlaneClient

Governance and operations

• PolicyPackManager
• ApprovalWorkflowEngine
• TenantManager
• TraceStore
• exportTraces
• generateEvidenceBundle

Persistence

• JSONFileMetadataStore
• FileTraceStoreBackend
• PostgresMetadataStore
• PostgresTraceStoreBackend

Local Service Example

import { ControlPlaneService } from '@veridex/agents-control-plane';

const service = new ControlPlaneService({
  dataDir: './data/control-plane',
  bootstrapTokens: ['root-secret'],
  traceRetentionDays: 90,
});

const tenant = await service.createTenant({ name: 'Acme' });

await service.registerWorkflow({
  id: 'wf_ops',
  name: 'Operations approval',
  description: 'Default approval path for risky actions',
  escalationChain: [
    {
      name: 'Ops',
      approvers: ['ops'],
      timeoutSeconds: 300,
      minApprovals: 1,
    },
  ],
  defaultMode: 'block',
});

const approval = await service.startApproval({
  workflowId: 'wf_ops',
  runId: 'run_123',
  agentId: 'treasury-agent',
  proposal: 'Transfer funds to vendor',
  riskScore: 0.82,
});

await service.ingestTrace({
  runId: 'run_123',
  agentId: 'treasury-agent',
  tenantId: tenant.id,
  startedAt: Date.now() - 1000,
  completedAt: Date.now(),
  state: 'completed',
  turnCount: 3,
  totalTokens: 180,
  events: [{ type: 'run_started' }, { type: 'run_completed' }],
});

console.log(approval.id);

Remote Service and Client Example

import {
  ControlPlaneService,
  createControlPlaneApp,
  RemoteControlPlaneClient,
} from '@veridex/agents-control-plane';

const service = new ControlPlaneService({
  dataDir: './data/control-plane',
  bootstrapTokens: ['admin-secret'],
});

const app = createControlPlaneApp(service);

const client = new RemoteControlPlaneClient({
  mode: 'managed',
  endpoint: 'http://control-plane.local',
  authToken: 'admin-secret',
  fetch: async (input, init) => app.request(input, init),
});

const health = await client.health();
const tenant = await client.createTenant({ name: 'Remote Tenant' });

console.log(health.ready, tenant.id);

Persistence Modes

File-backed mode

Good for:

• local development
• single-node deployment
• testing

This mode uses:

• JSONFileMetadataStore
• FileTraceStoreBackend

Shared Postgres mode

Good for:

• managed environments
• multiple service instances
• enterprise control-plane deployments

This mode uses:

• PostgresMetadataStore
• PostgresTraceStoreBackend

The Postgres path includes optimistic concurrency on metadata revisions so multiple service instances can coordinate against the same backing store.

CLI and Environment Variables

The package ships a CLI entrypoint:

veridex-control-plane

Important environment variables:

Variable	Purpose
VERIDEX_CONTROL_PLANE_STORAGE_BACKEND	file or postgres
VERIDEX_CONTROL_PLANE_POSTGRES_URL	Shared Postgres connection string
VERIDEX_CONTROL_PLANE_POSTGRES_SSL	Enable SSL for Postgres connections
VERIDEX_CONTROL_PLANE_POSTGRES_METADATA_TABLE	Optional metadata table override
VERIDEX_CONTROL_PLANE_POSTGRES_TRACES_TABLE	Optional traces table override
VERIDEX_CONTROL_PLANE_DATA_DIR	File-backed storage directory
VERIDEX_CONTROL_PLANE_HOST	Service bind host
VERIDEX_CONTROL_PLANE_PORT	Service bind port
VERIDEX_CONTROL_PLANE_BOOTSTRAP_TOKENS	Initial auth tokens
VERIDEX_CONTROL_PLANE_TRACE_RETENTION_DAYS	Trace retention window

How It Fits With the Runtime

Use the control plane when you want to move from:

• single-runtime local development
• to shared approvals and trace retention
• to a deployable, authenticated governance layer around many agents

Typical flow:

1. @veridex/agents executes runs and emits traces
2. traces and approval events are pushed into the control plane
3. operators or automated systems interact through the remote client or API
4. evidence bundles and audit exports become available for review or compliance

Deployment Surfaces

The repo includes deployment support for:

• Docker
• Docker Compose
• Kubernetes manifests
• Render
• Koyeb

These live under deploy/agents-control-plane/.

Known Rough Edges

• This package is still young enough that operational ergonomics will keep improving.
• You should still validate your own auth, retention, and escalation requirements before production rollout.
• Postgres is now supported for shared persistence, but production operators should still tune indexes, backups, monitoring, and secret management to their environment.

Contributions are especially welcome around ops guides, managed deployment examples, and tighter runtime-to-control-plane integration examples.