# Witina AI — Architecture

> Two pieces: a lightweight gateway inside your network that does all privileged local
> work, and a cloud console that is the brain. The gateway only dials out. Device
> credentials are stored encrypted on the gateway and never persisted in Witina's cloud.

Source: https://witinaai.com/ai/architecture.md
Part of the Witina AI machine-readable corpus — index: https://witinaai.com/llms.txt
Last updated: 2026-09-09

## The shape of the system

```
YOUR NETWORK                                  WITINA CLOUD
┌────────────────────────────────┐            ┌──────────────────────────────┐
│  Devices (switches, routers,   │            │  Console · topology ·        │
│  APs, firewalls)               │            │  alerting · change mgmt      │
│            ▲                   │            │                              │
│            │ SNMP / SSH / HTTP │            │  Device passwords:           │
│            ▼                   │  TLS out   │  never stored here           │
│  ┌──────────────────────┐      │───────────▶│                              │
│  │ Gateway              │      │            │                              │
│  │ credentials,         │      │            └──────────────────────────────┘
│  │ encrypted, here only │      │
│  └──────────────────────┘      │            No inbound ports. The gateway
└────────────────────────────────┘            initiates every connection.
```

**The gateway** runs inside your network. It performs discovery, polls devices, holds
credentials, and applies configuration changes. It needs to reach the devices you want
managed, and the internet. Nothing else.

**The cloud** stores topology, incidents, change managements, reporting and your user
accounts, and serves the console. Sensitive device access never has to leave your network.

## Why the gateway only dials out

The gateway opens an outbound TLS connection to the platform and proves its identity with
a signed token. It is provisioned once with a pairing token and renews itself afterwards.

Consequences that matter for a security review:

- You open **no inbound ports** and publish **nothing** to the internet.
- There is no management plane of yours exposed to attack from outside.
- Losing the internet link degrades reporting, not local operation.

## Credential handling

This is the design decision the rest follows from. When you add a credential in the
console:

1. It is relayed **through** to your gateway over TLS.
2. It is held in memory in transit, and written **only** to the gateway — encrypted.
3. Witina does **not** store device passwords in its cloud.

So there is no vault in Witina's cloud to breach, leak or subpoena. If you self-host, even
the transit stays on your own LAN.

## Encryption at rest on the gateway

Credential material on the gateway is encrypted at rest, using a model similar to LUKS or
FileVault: one key encrypts the data, and that key is never stored in the clear — it is
wrapped in a **keyslot**. You choose what holds the key that unwraps it:

| Keyslot | What holds the key | Property |
|---|---|---|
| **TPM-sealed** | A TPM 2.0 chip; never touches disk | A copied disk image or backup is useless without the physical hardware |
| **SaaS-assisted** | Split between gateway and cloud | Neither a stolen gateway nor a breach of Witina's cloud can decrypt alone — you need both halves |
| **Local key file** | A key file on the gateway | For fully offline/self-hosted deployments that depend on nothing outside your hardware |

You set the policy per gateway — require TPM, SaaS-assisted, or local file — and the
gateway reconciles its key storage to match.

**Crypto-shred on de-authorization.** Because SaaS-assisted mode needs the cloud's share to
unlock, de-authorizing a gateway withholds that share, making data on a lost or
decommissioned device cryptographically unrecoverable — whether or not the hardware is
ever physically recovered.

## Gateway privilege model

- **It is not root.** The gateway runs as an unprivileged user with a handful of narrow
  Linux capabilities — enough to sniff packets for discovery and serve firmware on one
  port. A compromise of the gateway process is not a root shell on your router.
- **Reboots and image upgrades** go through a separate, API-mediated path rather than
  being available to the gateway process itself.
- **Scoped credentials.** You decide which credentials may touch which devices.

## Where the gateway runs

Appliance, VM, or container — including a fully self-hosted single container (backend,
database, telemetry store, and a built-in gateway). Credentials are handled the same way in
every option. See https://witinaai.com/ai/deployment.md

## Tenancy and access control

An Organization / Division / Region hierarchy scopes every record, and access is checked
**per request** against the scope you are acting in — not once at login. The same
access-control engine serves the web console and the MCP server, so an AI agent cannot
take a parallel path that drifts from the UI's rules. See https://witinaai.com/ai/mcp.md

## Identity

Sign in with your own identity provider over standard **OIDC / OAuth (Authorization Code +
PKCE)**, configured globally or per organization, so account lifecycle stays where your IT
already manages it.

## Related

- Security posture: https://witinaai.com/ai/security.md
- Capabilities: https://witinaai.com/ai/capabilities.md
- Deployment: https://witinaai.com/ai/deployment.md