ArtzAIn

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 with a configuration change: a new endpoint and a key from it. Your application code stays the same.

In your VPC: design-partner program

Private deployment · design-partner program

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. The control plane can run fully inside your network: install it from mirrored images and pre-stage the model cache. The engine makes no calls to CogNEXUS Labs.

See the VPC boundary
Hosted plane

SDK only: decisions on the hosted plane

You install one zero-dependency package and point it at the hosted control plane. Requests are evaluated in memory over TLS; what persists is cryptographic evidence: a sha256 of the payload, plus the action, target and guard findings. The full payload is not stored. First governed decision in minutes: pip install artzain.

See the hosted boundary

Option one · your VPC

Private deployment · design-partner program

Everything inside the fence.

Engine, ledger, keys, and dashboard all run where your other regulated systems run. Outbound traffic goes only to the connectors, model downloads and advisory lookups you turn on.

Your boundary your VPC · on-prem · fully inside your network Your apps & agents + the artzain SDK, the Node client, an envelope base_url swap, or an OpenShell sidecar, all pointed at your instance HTTPS ArtzAIn control plane: your instance Decision API · governance envelope · agent crew · dashboard core profile: CPU-only, no GPU, no local model full profile: + self-hosted Gemma inference on your GPU deploy: Docker Compose · Helm · Terraform. Schema self-creates on boot, no migration scripts to run fails closed: if the ledger is unwritable, it refuses to decide PostgreSQL: yours receipts ledger · policy bundles · context · graph, all Postgres-native: no graph database, no separate vector store required Ed25519 signing keys generated locally on first boot; private keys never leave the host back the key directory up: unrecoverable if lost Database backups: yours artzain local dumps the database before every upgrade; on Helm or Terraform, your Postgres's own backups (PITR) cover it Operator browser dashboard served from your instance; policy bundles signed in-browser: signing keys stay on the machine Your data connectors CRM · mail · drive · payments · code, plus read-only agent discovery across MCP, Kubernetes, and CI/CD only what you enable Model downloads: optional full profile: on first boot, and the coder model on first auto-fix; pre-stage the cache and it never happens at all ArtzAIn hosted plane outside your network: the engine makes no calls to CogNEXUS Labs no traffic Your auditor you hand over an evidence bundle; artzain audit verify checks every record hash and signature offline, no network. Intact bundles verify as SELF-ATTESTED today you export
Engine, ledger, keys, and dashboard inside your perimeter. Outbound traffic goes only to the connectors, model downloads and advisory lookups you turn on. The only artifact designed to leave is the evidence bundle you choose to export.

Option two · hosted plane

One package on your side. Evidence, not content, on ours.

Three integration paths cross the wire: the Decision API (from your code, from the ArtzAIn MCP gateway in front of your MCP servers, or from the sidecar beside an OpenShell gateway), 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 (TLS :443) Your boundary laptop · CI · your VPC: your code never leaves it Your application / agent code business logic, prompts, data: nothing is uploaded as code decide(action, target, payload, kind) Python SDK: pip install artzain Python ≥ 3.10 · zero dependencies · pure stdlib guard library, the same code the plane runs: injection · destructive-action · policy rules prompt defense · tool-call contracts · PII counts + its own kill switch and hash-chained audit log no API key → decide() runs the first three, offline:true, zero egress, no sealed receipt Brownfield agent: any OpenAI-compatible client no code change beyond one line: base_url → …/api/v1/envelope/v1 CLI · your operator's browser artzain policy keygen : the private key is created here and stays here (CLI file or browser WebCrypto) artzain audit verify : evidence recomputed offline Nothing on this side needs Docker, a GPU, or a vendor library. Node option: @cognexuslabs/artzain (remote-only client) OpenShell: a sidecar decides each gateway write POST /api/v1/decisions agent_did · action · target · payload allow / deny / review + receipt id optional SDK events: redacted previews only chat completion: prompt + tool calls response + decision headers signed policy bundle: rules + signature (only the public key registers) evidence bundle: receipts · seals · proofs Hosted plane the hosted control plane, multi-tenant Decision engine: the enforcer pipeline gates: kill switch · ledger breaker (fails closed) privacy-guardian → prompt-injection → destructive-action → tool contracts → MCP tool supply → your bundle → identity → registry → compliance-warden → fraud-sentry + framework overlays: seven first-party bundles worst vote wins · signed and chained before the response returns payload evaluated in memory, never written to disk Sealed ledger: the system of record hash-chained · Ed25519-signed · Merkle-sealed ≤ 60 s payload kept as a sha256 plus action, target and findings; the full payload is not stored when the privacy guard finds personal data, it records how many, never the values retained per your plan (up to 7 years by agreement) · append-only, enforced in the database Policy bundles · review queue · dashboard your signed bundles: draft → shadow → active. Unsigned or tampered uploads rejected at the gate review outcomes resolved by your operators; each resolution is itself a sealed receipt telemetry surfaces show redacted previews only envelope forward Your model provider: third party forwarded with your provider key (held encrypted), only after the inbound decision allows; the output is decided too
Decision payloads do cross the wire (that is what gets evaluated), but they are processed in memory and persisted only as a hash plus redaction-safe findings. With no API key configured, decide() runs three of the same guards locally (prompt injection, destructive action and policy rules) and nothing leaves your boundary at all; PII detection and tool-call contracts need the plane.

The wire

What crosses the wire, and what the plane keeps.

The hosted plane's privacy invariant, row by row. To prove which payload was decided, hash your candidate and compare: the record is built so you can check the answer yourself.

What travelsDirectionWhat the plane keepsNotes
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; the full payload is not stored.
Decision metadata: identity, action, target, kind 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 per your plan (up to 7 years by agreement).
Decision context: optional tags and attributes you → plane What the votes read Not stored as sent. An enforcer that reads a key, such as a lawful-basis tag, records what it read in its own sealed vote; a key no enforcer reads reaches no receipt. Keep your own correlation data keyed by the decision id.
Personal data inside payloads you → plane Counts only When the privacy guard finds personal data, checksum-validated detectors record how many (ssn: 2); 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.
OpenShell gateway writes: from the sidecar beside your gateway sidecar → plane Receipts and catalog rows One decision per governed operator write (policy, settings, providers, sandbox deletion, services, SSH sessions), signed and chained before the gateway applies it. On the gateway's own credential, the sidecar also sends a heartbeat each minute (versions and decision latency) and an inventory every five minutes (sandbox ids, names, phases, policy hashes, and provider profile names, never provider secrets).
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 inclusion proofs, framework artifacts. artzain audit verify checks every record hash and signature offline, with zero network, checks the hash chain wherever your receipts are consecutive, and proves each receipt is included under its seal's signed Merkle root. A hosted-plane seal also covers other tenants' receipts, so the verifier proves inclusion there instead of recomputing that root, and says so. 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 Not carried Decision calls never carry your source code, model weights, or private signing keys. There is no code-upload path in the product. Guards run either in your process or against the single request payload you send.

What transits: on the hosted plane, the content you gate passes through our infrastructure (in memory, over TLS), though it is never persisted. If the transit itself is unacceptable (regulated data, fully private networks), the VPC deployment exists for that.

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

pip install artzain · v0.6.x · Apache-2.0
  • 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 · local up / upgrade · connect openshell · audit export / verify · policy keygen / sign / push / promote
Installed in your boundary

Node client

@cognexuslabs/artzain · Apache-2.0
  • Remote-only client: decide(), events, identity
  • No local guards yet: parity is on the roadmap; the offline fallback is Python-only today
Installed in your boundary

Orchestrator packages

OpenClaw plugin · n8n nodes · Grok Bot skill
  • For agents built on OpenClaw, n8n or Grok Bot: each calls the Decision API or the envelope over HTTPS
  • Fail closed: an error or a redirect blocks the call, and redirects are never followed, so the key stays with the host you configured
  • Published to npm with signed provenance, like every ArtzAIn package
Installed in your boundary

MCP gateway

@cognexuslabs/artzain-mcp-gateway · Apache-2.0
  • An MCP server in front of your MCP servers: your agent sees one tool list, each tool named <upstream>__<tool>
  • Every tools/call asks the Decision API first, and only allow is forwarded
  • A deny, a review or an outage returns an error and never reaches the upstream: there is no offline path
Installed in your boundary

Governance envelope

/api/v1/envelope/v1 · per-agent credential
  • Nothing to install: repoint any OpenAI-compatible agent's base_url
  • Inbound and model-output decisions signed and chained per call, under the agent's own identity
  • Fails closed by default; credentials shown once, revocable from the dashboard
Config change in your boundary

OpenShell sidecar

artzain[openshell] · signed image on GHCR
  • Runs beside your NVIDIA OpenShell gateway and serves its interceptor: each governed write is decided and signed before the gateway applies it
  • artzain connect openshell up binds it on deb or rpm, Docker Compose, the snap, Homebrew on Apple-silicon Macs, or a Kubernetes Helm release
  • Fails closed: a deny, a review, a timeout or an outage refuses the write
Installed in your boundary

Control plane: core

GPU-free image · Compose · Helm · Terraform
  • 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
  • One-line install on a single host (artzain local): digest-pinned images, and a database dump before every upgrade
  • Helm chart ships health probes, CPU autoscaling, and a persistent volume for signing keys
VPC option: your infrastructure

Control plane: full

CUDA image · self-hosted inference
  • 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, plus ~62 GB the first time auto-fix runs its coder model; pre-stage both for installs without internet access
VPC option: your infrastructure

Operator dashboard

served by whichever plane you run
  • 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, hosted or VPC
Served by the plane

Requirements

What it takes to run.

Both deployment modes, quantified: what we provision, and what your team brings.

Hosted planeDetail
RuntimePython ≥ 3.10 on any OS, or Node.js for the remote client. No Docker, no GPU, no database.
NetworkOutbound HTTPS (443) to the hosted plane. The SDK sends an identifiable User-Agent for your egress allowlists.
CredentialsOne 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.
LatencyDecides in the path of the action, before it runs. Idempotent request ids make timeouts safe to retry.
Failure handlingIf the ledger is unwritable the plane refuses to decide, a typed 503. Treat it as deny; never act on a 503.
Your VPCCore profile: GPU-freeFull profile
PlatformDocker ≥ 24 with Compose v2, or Kubernetes with the Helm chart, or Terraform on AWS
ComputeCPU only; autoscaling on CPU for the decision pathNVIDIA GPU with the container toolkit (CUDA 12.6, driver 560 or later)
DiskDatabase volume + key directory+ ~16 GB model cache, and ~62 GB more for the auto-fix coder; pre-stageable for installs without internet access
DatabasePostgreSQL: bundled subchart or your own managed instance. The schema self-creates idempotently on boot; there are no migration scripts to run.
Secrets floorA strong JWT secret and an API-key pepper (the Helm chart refuses to render without both), 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 floorPostgres-backed sealing and a seven-year evidence floor for the compliance bundles. A plan with a shorter window can adopt a bundle once the team owner acknowledges the difference, and the evidence pack records it.
EgressNone required. Optional: the data connectors you enable; OSV vulnerability lookups (package names and versions) when Code Bastion scans a repository you connect; OpenShell's security advisories from GitHub while an OpenShell gateway is connected; and the model downloads 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 checks every record hash and signature in an exported bundle, the artifact you hand an assessor, with no network (signatures need artzain[verify]). It checks the hash chain wherever the receipts are consecutive and proves each receipt is included under its seal's signed Merkle root. 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. Root-anchored verification, which needs the pinned CogNEXUS Evidence Root, lets an assessor check a bundle independently of the server that produced it. Today no Evidence Root is pinned, so bundles verify as self-attested. Export profiles exist for all seven first-party bundles: EU AI Act, NIST AI RMF, ISO/IEC 42001, SOC 2 AI controls, GDPR, HIPAA and SOX, each with explicit 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. An approval releases one decision only, held to the exact payload the reviewer saw.

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.