Shield360 › Architecture
What runs where,
and what leaves.
This page is written for the architect who has to draw the diagram and the reviewer who has to sign it. It states what each component is, what crosses each boundary, where data comes to rest, and what the product cannot do by construction.
01 · Components
Seven pieces, four of them optional
Seven components.
Four are optional.
| Component | Runs on | What it does |
|---|---|---|
| Platform | Your cluster | The dashboard and its API. Serves every screen, holds roles and permissions, writes the audit log, and exposes the MCP gateway. |
| Collector agent | Each machine | A single binary. Reads what AI tools write about themselves and which application is in front; reports outbound over TLS. No certificate, no proxy change, no listening socket. |
| OpenTelemetry collector | Your cluster | Receives OTLP over gRPC and HTTP from instrumented applications, managed through an OpAMP control plane. |
| Controller (optional) | Your cluster | eBPF-based discovery and SDK injection for LLM workloads already running, where instrumenting the source is not practical. |
| SDKs (optional) | Your applications | Python, TypeScript and Go. Any OTLP exporter works too — the SDK is a convenience, not a lock-in. |
| Browser extension (optional) | Managed Chrome and Edge | Acts on AI chat sites under the organization's enforcement policy: allows, warns about or blocks each AI tool, and warns about, masks or blocks sensitive data in a prompt before it is sent. |
| AI proxy (optional) | A machine, a container, or hosted by us | Applications point their base URL at it, so it needs no root certificate. Applies the same enforcement policy, and can warn on or refuse a model outside the approved list. Only traffic you route to it passes through it. |
ClickHouse
Telemetry and collector data — usage, activity, spans, guard events. This is where the retention time-to-live is enforced, by the engine rather than by a job that can be skipped.
Postgres
Accounts, organizations, projects, roles, permissions, subscriptions and the audit log.
Both are your instances in a self-hosted deployment. Nothing is stored outside them.
02 · The boundary
What crosses, and what does not
What leaves a machine.
The collector's outbound payload is deliberately narrow. It is worth reading the second column against the first: several things a reviewer expects to find in a monitoring agent are absent, and absent structurally.
| Category | Leaves | Detail |
|---|---|---|
| AI tool usage | Yes | Tool, model, responses, token counts, and the repository or project a session belonged to. |
| Machine and user identity | Yes | Hostname, operating system, the signed-in user's account name. |
| Application time | Yes | Which application was in front, and for how long. No window titles and no file names. |
| Data protection events | Yes | That a rule fired, which rule, the kinds of data found and the outcome. The detected value is kept only as a keyed fingerprint, and only if an administrator opts in. |
| Network observations | Only if enabled | Process and destination host for connections to AI providers, from the OS socket table. Off by default. |
| Browsing | Only if enabled | Registrable domain unless explicitly widened. No page titles. Off by default. |
| Prompt and response bodies | By setting | Not stored by default. Coding-agent prompts are read on the machine so data protection can act; their text, and any other prompt, response or tool content, is stored only if an administrator opts in, and an environment can only store less than its organization. Secrets are always scrubbed from what is stored. |
| Source code | No | What an AI session produced is measured; the code itself is not uploaded. |
| Keystrokes, mouse, screenshots | No | No table exists that could hold them. |
| Packet capture | No | No capture of any kind, at any layer. |
03 · Enrollment
One key, many tokens
One key for the fleet,
one token per machine.
Create an install key
Under Visibility › Setup. One key covers the whole fleet, which is what makes it suitable for an MDM, Intune or Jamf rollout. Keys are reusable until revoked.
Enroll, with the key in the environment
Passed as SHIELD360_INSTALL_KEY so it never reaches the process table, where any other user on the machine could read it.
The machine exchanges it for its own token
From that point the install key is not used again on that machine. The per-machine token is revocable on its own without touching the rest of the fleet.
Hooks install for the agents it finds
Claude Code, Cursor and Codex. The collector re-checks hourly, so an agent installed next month is picked up without anyone running a command.
Policy is fetched, and safe by default
Browsing and network observation stay off unless the organization's collection policy turns them on. If the platform is unreachable, the agent observes nothing rather than falling back to a wider policy.
04 · Deployment
Three shapes
Three deployment shapes.
Self-hosted
The platform, the OpenTelemetry collector and optionally the controller run in your own environment — on Docker, or on Kubernetes with manifests we provide — against your own ClickHouse and Postgres. Collectors report to your host, not ours. This is the shape most regulated customers adopt.
Air-gapped
The same deployment with no egress. There is no licensing call-home, no telemetry back to us, and no feature that degrades without an outbound connection. Updates are images you pull on your own schedule.
Hosted
Run by us, with a database per tenant rather than a shared table carrying a tenant column. A query that omits the filter cannot return another customer's rows, because those rows are not in the database the query is connected to.
| In your environment | Hosted by us | |
|---|---|---|
| Who operates it | Your team | Shield360 |
| Where the data lives | Your ClickHouse and Postgres | A database dedicated to your organization |
| Outbound connections | None required, including air-gapped | Collectors to the hosted service over TLS |
| Updates | Images you pull when you choose | Applied by us |
| Identity | Your OIDC issuer | Your OIDC issuer |
| Features | The full platform | The full platform |
05 · Identity
Your issuer, our permissions
Your identity provider decides who.
Shield360 decides what.
OIDC against your own issuer
Configured with an issuer, a client ID and a secret; the discovery document does the rest. That covers Okta, Entra ID, Ping and anything else standards-compliant. The authorization code flow uses PKCE with S256.
Roles and permissions live here
Permissions are checked on every route, not only in the interface. A request that fails the check is refused and the refusal is written to the audit log as a denied event — which is what lets you demonstrate the control is working rather than assert it.
Custom roles, per organization
Beyond the built-in roles, an organization defines its own from the permission catalog, so “can read the spend report but not the audit log” is a role you can actually create.
Projects and environments are boundaries
Every screen is scoped to an organization, a project and an environment. A permission granted in one project does not carry into another, and production and staging do not share a dataset.
06 · Interfaces
Ports and protocols
What listens, and for what.
| Interface | Protocol | Purpose |
|---|---|---|
| Dashboard and API | HTTPS | Every screen, the REST API, and the collector's reporting endpoint. |
| OTLP ingest | gRPC · HTTP | Traces, metrics and logs from instrumented applications and any OTLP exporter. |
| MCP gateway | HTTPS | One endpoint for agents, each authenticating with its own token against its own grants. |
| AI proxy (optional) | HTTP · HTTPS | A base URL for applications. Run locally it listens on loopback only, unless you allow remote clients with an access token; hosted, it sits behind TLS. |
| Collector agent | Outbound only | Listens on nothing. It opens no socket and accepts no inbound connection. |
Ports are configurable and differ between the Docker and Kubernetes deployments. Exact values, resource sizing and high-availability guidance come with the deployment documentation rather than from a marketing page that would go stale.
Send us the architecture review.
If your reviewers have a standard pack, we would rather answer it against the code than against a slide.