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.6.x · python ≥ 3.10 · deploy: compose | helm | terraform
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.
The wire
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 every hash, chain link, Merkle root, and signature offline, with zero network. Today every intact bundle verifies as SELF-ATTESTED: internally consistent, but nothing yet ties its signing key to CogNEXUS. |
| Your source code · model weights · private signing keys | n/a | 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.
Both deployment modes, quantified: what we provision, and what your team brings.
| 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 | 184ms median per decision, end-to-end. 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 guard code on both sides of the wire. The SDK's six guard modules are derived mechanically from the plane's enforcer core, and the engine's build fails on drift, so a guard fix cannot land on one side only. Offline, decide() runs three of them, so a call that passes locally can still come back review or deny from the plane.
- 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 runs offline and says exactly what it proved. artzain audit verify recomputes every hash, chain link, Merkle root, and signature in an exported bundle, the artifact you hand an assessor, with no network (signatures need artzain[verify]). Edit a leaf and verification fails, naming the sequence number that broke. An intact bundle verifies as SELF-ATTESTED: internally consistent, but nothing yet ties its signing key to CogNEXUS. Only ATTESTED, which needs the pinned CogNEXUS Evidence Root, removes the need to trust the server that produced the bundle, and as of artzain 0.6.19 that root is not pinned. 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.