Architecture · the customer view
Your boundary, mapped.
Before Legal, Security, or the CISO says yes, they ask the same three questions: what gets installed inside our perimeter, what does it need to run, and exactly which bytes leave. This page answers all three — drawn from the control plane's own documentation, nothing aspirational.
sdk artzain 0.3.x · python ≥ 3.10 · deploy: compose | helm | terraform · verified 2026-08
Two ways to run it
Same engine, same policies. You choose the perimeter.
Everything below follows from this one choice — and you can start on one and move to the other without changing a line of application code.
The whole control plane, inside your perimeter
The engine deploys next to your own PostgreSQL — Docker Compose, Helm, or Terraform. Signing keys are generated on your hosts and never leave. Designed for zero vendor callouts; runs air-gapped with a pre-staged model cache. Nothing is sent back to CogNEXUS Labs — no license pings, no usage phoning home.
See the VPC boundarySDK only — decisions on the hosted plane
You install one zero-dependency package and point it at the managed control plane. Requests are evaluated in memory over TLS; what persists is cryptographic evidence — a sha256 of the payload, never the payload itself. First governed decision in minutes: pip install artzain.
See the managed boundaryOption one · your VPC
Everything inside the fence.
Engine, ledger, keys, and dashboard all run where your other regulated systems run. Outbound traffic exists only where you create it.
Option two · managed cloud
One package on your side. Evidence, not content, on ours.
Three integration paths cross the wire — the Decision API, the governance envelope for agents you can't modify, and the policy control plane. Telemetry is a fourth, dashed: off until you turn it on.
What crosses the wire — and what the plane keeps.
The managed plane's privacy invariant, row by row. To prove which payload was decided, hash your candidate and compare — the record is built so you never have to trust us to answer.
| What travels | Direction | What the plane keeps | Notes |
|---|---|---|---|
| Decision payload — the text or tool call being gated (≤ 256 KiB) | you → plane | Hash only | Evaluated in memory by the enforcer pipeline; the sealed receipt records the payload's sha256, never the payload. |
| Decision metadata — identity, action, target, kind, context tags | you → plane | Sealed receipt | This is the audit record: the verdict, every enforcer's vote and findings, and the exact signed policy version that ruled. Retained 7 years. |
| Personal data inside payloads | you → plane | Counts only | Checksum-validated detectors report ssn: 2-style counts; matched values never appear in findings or receipts. |
| SDK telemetry — optional | you ⇢ plane | Event rows | Only with an API key set. Event type, package and runtime versions, token counts, and a ≤ 96-character redacted preview — never full prompts. No key, no traffic. |
| Envelope chat traffic — brownfield agents | you → plane → provider | Hash only | The full prompt transits for governance, then forwards to your own model provider using your upstream key, held encrypted. Inbound and output decisions both seal — hashes and findings, not content. |
| Policy bundles | you → plane | Signed rules | Rules plus your Ed25519 signature. The private key is generated on your side — CLI or in-browser — and never transmitted; only the public key registers. |
| Connector content — only if you enable data connectors | provider → plane | Context store | Pulled into the context engine for retrieval, with the redaction boundary at ingestion: identifiers become type tokens before any row persists. Opt-in per connector; tokens held encrypted. |
| Evidence bundle | plane → you | You keep it | Self-contained export — receipts, seals, Merkle proofs, framework artifacts. artzain audit verify recomputes everything offline: zero network, zero server trust. |
| Your source code · model weights · private signing keys | — | Never sent | There is no code-upload path in the product. Guards run either in your process or against the single request payload you send. |
The honest caveat: on the managed plane, the content you gate does transit our infrastructure — in memory, over TLS — even though it is never persisted. If the transit itself is unacceptable — regulated data, air-gapped estates — that is exactly what the VPC deployment exists for.
The inventory
What gets installed, component by component.
Everything on your side is deliberately light: one pure-stdlib package, one config change, or one container image — your choice of depth.
Python SDK
- Python ≥ 3.10, zero mandatory dependencies — pure standard library, any OS
- Full local-guard library — the same code the plane's enforcers run, mechanically synced
- decide() client with an offline fallback and a hash-chained local audit trail
- CLI: login · quickstart · audit export / verify · policy keygen / sign / push / promote
Node client
- Remote-only client: decide(), events, identity
- No local guards yet — parity is on the roadmap; the offline fallback is Python-only today
Governance envelope
- Nothing to install — repoint any OpenAI-compatible agent's base_url
- Inbound and model-output decisions sealed per call, under the agent's own identity
- Fails closed by default; credentials shown once, revocable from the dashboard
Control plane — core
- The full decision path: Decision API, sealed ledger, policy bundles, registry, dashboard
- No local model — LLM-dependent operator features mark themselves degraded instead of crashing
- Helm chart ships health probes, CPU autoscaling, and a persistent volume for signing keys
Control plane — full
- Everything in core, plus self-hosted Gemma-family inference on your GPU
- Powers operator chat, analysis, and code auto-fix — the decision path itself never needs the model
- ~16 GB model cache: pulled on first boot, or pre-staged for air-gapped installs
Operator dashboard
- Review queue, audit log with chain verification, policy editor, agent registry, connectors
- Policy bundles signed in the browser — private keys never reach any server
- Nothing to install: it ships with the plane, managed or VPC
Requirements
What it takes to run.
| Managed cloud | Detail |
|---|---|
| Runtime | Python ≥ 3.10 on any OS, or Node.js for the remote client. No Docker, no GPU, no database. |
| Network | Outbound HTTPS (443) to the managed plane. The SDK sends an identifiable User-Agent for your egress allowlists. |
| Credentials | One API key, from a device-code login or the dashboard. Keys can be bound to a single agent identity, so a leaked key cannot impersonate the rest of your fleet. |
| Latency | Engine target: P95 under 200 ms per decision, plus your round trip. Idempotent request ids make timeouts safe to retry. |
| Failure handling | If the ledger is unwritable the plane refuses to decide — a typed 503. Treat it as deny; never act on a 503. |
| Your VPC | Core profile — GPU-free | Full profile |
|---|---|---|
| Platform | Docker ≥ 24 with Compose v2, or Kubernetes with the Helm chart, or Terraform on AWS | |
| Compute | CPU only; autoscaling on CPU for the decision path | NVIDIA GPU with the container toolkit (CUDA 12.1) |
| Disk | Database volume + key directory | + ~16 GB model cache, pre-stageable for air-gap |
| Database | PostgreSQL — bundled subchart or your own managed instance. The schema self-creates idempotently on boot; there are no migration scripts to run. | |
| Secrets floor | A strong JWT secret, and the Ed25519 key directory on a persistent, backed-up volume — the signing keys are generated there on first boot and are unrecoverable if lost. | |
| Audit floor | Postgres-backed sealing and a 7-year retention floor. The compliance bundles refuse to activate unless the deployment actually meets it — the gate is machine-checked, not a checkbox. | |
| Egress | None required. Optional: the data connectors you enable, and the one-time model download on the full profile. | |
For your security review
Six claims your team will want to test.
Each of these is a property of the build, not a promise in a slide. Bring your red team.
- →Same guards on both sides of the wire. The SDK's local guards are derived mechanically from the plane's enforcer core, and the build fails on drift — local screening and plane decisions agree by construction.
- →Keys are asymmetric on purpose. Ledger-signing keys live where the plane runs — your volume, in the VPC option. Policy-signing private keys always live with you, and only public keys register. Rotation keeps historical receipts verifiable.
- →Verification needs no trust in any server. artzain audit verify recomputes every hash, chain link, Merkle root, and signature from an exported bundle, fully offline — the artifact you hand an assessor. Export profiles exist for the EU AI Act, NIST AI RMF, ISO 42001, and SOC 2, with honest non-claims: evidence supports a program; it is not a certificate.
- →Fail-closed is the default posture. If the ledger cannot be written, the plane returns a typed error rather than deciding unrecorded — and a specialist enforcer that throws becomes a deny vote unless your bundle names an explicit fallback.
- →Telemetry is opt-in by construction. Without an API key in the environment, the SDK's cloud module returns before opening a socket. When enabled, it sends redacted previews and counts — never full prompts.
- →Your review queue, your humans. Every review outcome is resolved by your operators, and each resolution is itself a sealed receipt linked to the original decision.
Next step
Walk the boundary with your architects.
A pilot starts with a scoping call and ends with the control plane live in your VPC — week four, your keys, your perimeter.