# How It Works

> **Coming Soon**: Architecture is based on current design and may be adjusted upon release.

***

This page explains from a **systems perspective** how toani Control's planes work together and how a typical "execution request with policy and risk controls" flows through components.

> For product introduction, see [toani Control Product Overview](/about-toani/toani.ai.md). For Execution Plane implementation details, see [Execution Plane Technical Architecture](/toani-control/execution-plane.md).

***

## Positioning in toani.ai

toani Control serves **enterprise customers**, packaging **credential custody, policy decision-making, isolated execution, and audit proof** as an integrable cloud product. Its relationship with **toani Vault** can be summarized:

| Dimension               | toani Vault                                                                                              | toani Control                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Primary Audience        | Developers integrating TEE credential libraries and sandboxes                                            | Enterprise tenants: console, policies, batch/HITL, multi-connector     |
| Credential Storage Form | Consistent with existing toani Vault / PostgreSQL implementations (documentation centers on toani Vault) | Design: HashiCorp Vault KV plus TEE sealing layer, namespace isolation |
| Execution Form          | TEE-internal Chromium (toani Vault)                                                                      | SGX decryption/Token plus SEV-SNP/gVisor connectors (design)           |

The two can **complement each other**: enterprises can use toani Control's policies and connector orchestration while tapping into toani.ai / zkMe ecosystem capabilities at identity and proof layers.

***

## Three-Plane Overview

<figure><img src="/files/2QbyrjnFVPoy7UYBDNRV" alt=""><figcaption></figcaption></figure>

***

## L1: Credential Plane

* **Responsibility**: enterprise manages "who owns which credentials, in which namespace, sensitivity level, rotation policy."
* **Interaction**: admins write credentials via console or Management API; **responses never include plaintext**.
* **Isolation**: across tenants, **key derivation paths, Vault namespaces, and network routing** are hierarchically isolated (design goal).

***

## L2: Policy Plane

* **Responsibility**: defines which **agent** under which **scenario (A/B/C)** can execute which **actions** on which **credential namespaces**, and attaches **constraints** and **HITL**.
* **Policy attributes (logical model)**: `policy_id`, version, `agent_binding`, `credential_ref`, `allowed_actions`, `constraints`, `hitl`, optional `zkme_requirements`, `audit_level`, creator, and signature.
* **Risk stratification (Tier)**:
  * **Tier 0**: auto-approval (e.g., read-only, low amount, repeated successful pattern).
  * **Tier 1**: soft approval (e.g., push confirmation).
  * **Tier 2**: hard approval (e.g., PIN/biometrics, irreversible action, high-value trade).

**Pre-flight check (concept)**: action whitelist, constraint expressions, cumulative limit, zkKYC freshness (if configured), risk Tier routing to HITL.

**Post-flight audit (concept)**: Execution Receipt and **pre-approved request's param hash** consistency, cumulative counter update, compliance webhook, anomaly queue.

***

## L3: Execution Plane

* **Only place** where **credential plaintext** is designed to exist transiently: decrypted in SGX, injected to connector via **RA-TLS**, **memzero\`'d after use**.
* Outputs **Execution Receipt** (verifiable) and **auditRef** (immudb reference).

***

## Complete Data Flow Example: Wealth Management Agent Buys Stock

Below is an illustrative flow; exact field names and endpoints follow the released API.

<figure><img src="/files/lZnoHbMOjybr3XfXzqDM" alt=""><figcaption></figcaption></figure>

***

## Three Execution Modes

| Mode                     | When                                   | Behavior Summary                                                                                          |
| ------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Sync**                 | Low latency, read-only or Tier 0 write | API blocks until completion, returns Receipt                                                              |
| **Async + HITL**         | Tier 1/2                               | Returns `pending_hitl` / `executionId` first, get final state via Webhook or polling                      |
| **Pre-authorized Batch** | Policy jobs, rebalancing               | User/admin pre-signs authorization window plus quota; within window, single executions skip per-item HITL |

***

## Multi-Tenancy and Observability

**Multi-tenancy**: L1 master key per tenant isolation plus Vault namespaces plus routing isolation; compromise of one tenant's namespace should not leak another tenant's key.

**Observability**: execution monitoring, HITL activity, policy version chain, compliance report export, anomaly alerts (capacity, time window, policy near-miss, repeated rejection, etc.) – all source from **audit layer data**, ensuring "no silent history modification."

***

## Integration Method Comparison (Planned)

| Method             | Use Case                           | Documentation                                                    |
| ------------------ | ---------------------------------- | ---------------------------------------------------------------- |
| **TypeScript SDK** | Node.js / OpenClaw, etc            | [SDK](/toani-control/getting-started/sdk.md)                     |
| **HTTP API**       | Non-TypeScript clients             | [API Reference](/toani-control/getting-started/api-reference.md) |
| **Webhook**        | HITL and async execution callbacks | Above (preview callback section)                                 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toani.ai/toani-control/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.