# hamdok/aestheris architecture

> Architecture diagram of the GitHub repository hamdok/aestheris, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamdok/aestheris
- Repository: https://github.com/hamdok/aestheris

## Overview

Aestheris is a local trust gateway for AI agents. Its main workflow is `aestheris run`: load policy and vault secrets, launch a loopback proxy, then run the agent in a sandbox with phantom credentials; proxy requests are checked, privacy-filtered, forwarded, and audited, with sensitive actions optionally awaiting human approval. Separate CLI capabilities initialize configuration, scan for exposure, and inspect audit evidence. The tree and sampled excerpts support the principal wiring; some CLI dispatch and subsystem details are documented but not fully sampled.

Main entry points: [`src/proxy.rs`](https://github.com/hamdok/aestheris/blob/main/src/proxy.rs) (Local gateway), [`src/run.rs`](https://github.com/hamdok/aestheris/blob/main/src/run.rs) (Run coordinator), [`src/main.rs`](https://github.com/hamdok/aestheris/blob/main/src/main.rs) (CLI dispatch), [`src/audit.rs`](https://github.com/hamdok/aestheris/blob/main/src/audit.rs) (Audit log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_main["CLI dispatch<br/>[main.rs]"]
  node_init["Initialize setup<br/>[init.rs]"]
  node_scan["Exposure scan<br/>[scan.rs]"]
  node_project_scan["Project findings<br/>[project_scan.rs]"]
  node_secret["Secret detection<br/>[secret.rs]"]
  node_gitleaks["Gitleaks rules<br/>[gitleaks.rs]"]
end

subgraph group_gateway["Gateway controls"]
  node_run["Run coordinator<br/>[run.rs]"]
  node_policy["Policy rules<br/>[policy.rs]"]
  node_proxy["Local gateway<br/>[proxy.rs]"]
  node_sandbox["Agent sandbox<br/>[sandbox.rs]"]
  node_linux_sandbox["Linux isolation<br/>[sandbox_linux.rs]"]
  node_approval["Human approval<br/>[approval.rs]"]
end

subgraph group_privacy["Privacy and secrets"]
  node_vault[("Encrypted vault<br/>[vault.rs]")]
  node_phantom["Phantom tokens<br/>[phantom.rs]"]
  node_privacy_shield["Privacy shield<br/>[privacy.rs]"]
end

subgraph group_evidence["Evidence and review"]
  node_audit[("Audit log<br/>[audit.rs]")]
  node_report["Audit reports<br/>[report.rs]"]
end

node_user(("Developer"))
node_agent(("AI agent"))
node_provider(("API / model provider"))

node_user -->|"runs command"| node_main
node_main -->|"initializes"| node_init
node_main -->|"starts scan"| node_scan
node_scan -->|"checks project"| node_project_scan
node_project_scan -->|"detects secrets"| node_secret
node_project_scan -->|"uses rules"| node_gitleaks
node_main -->|"starts session"| node_run
node_run -->|"loads policy"| node_policy
node_run -->|"unlocks secrets"| node_vault
node_run -->|"starts gateway"| node_proxy
node_run -->|"launches agent"| node_sandbox
node_sandbox -->|"uses Linux isolation"| node_linux_sandbox
node_run -->|"opens approval channel"| node_approval
node_run -->|"records session"| node_audit
node_run -->|"launches with phantom credentials"| node_agent
node_agent -->|"sends requests"| node_proxy
node_proxy -->|"checks route rules"| node_policy
node_proxy -->|"validates token"| node_phantom
node_proxy -->|"filters payloads"| node_privacy_shield
node_proxy -->|"requests decision"| node_approval
node_proxy -->|"forwards request"| node_provider
node_provider -->|"returns response"| node_proxy
node_proxy -->|"records requests"| node_audit
node_main -->|"handles approval command"| node_approval
node_main -->|"reads audit events"| node_audit
node_main -->|"renders report"| node_report
node_audit -->|"provides events"| node_report

click node_main "https://github.com/hamdok/aestheris/blob/main/src/main.rs"
click node_init "https://github.com/hamdok/aestheris/blob/main/src/init.rs"
click node_scan "https://github.com/hamdok/aestheris/blob/main/src/scan.rs"
click node_project_scan "https://github.com/hamdok/aestheris/blob/main/src/project_scan.rs"
click node_run "https://github.com/hamdok/aestheris/blob/main/src/run.rs"
click node_policy "https://github.com/hamdok/aestheris/blob/main/src/policy.rs"
click node_proxy "https://github.com/hamdok/aestheris/blob/main/src/proxy.rs"
click node_sandbox "https://github.com/hamdok/aestheris/blob/main/src/sandbox.rs"
click node_linux_sandbox "https://github.com/hamdok/aestheris/blob/main/src/sandbox_linux.rs"
click node_approval "https://github.com/hamdok/aestheris/blob/main/src/approval.rs"
click node_vault "https://github.com/hamdok/aestheris/blob/main/src/vault.rs"
click node_phantom "https://github.com/hamdok/aestheris/blob/main/src/phantom.rs"
click node_privacy_shield "https://github.com/hamdok/aestheris/blob/main/src/privacy.rs"
click node_audit "https://github.com/hamdok/aestheris/blob/main/src/audit.rs"
click node_report "https://github.com/hamdok/aestheris/blob/main/src/report.rs"
click node_secret "https://github.com/hamdok/aestheris/blob/main/src/secret.rs"
click node_gitleaks "https://github.com/hamdok/aestheris/blob/main/src/gitleaks.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_init,node_scan,node_project_scan,node_secret,node_gitleaks toneBlue
class node_run,node_policy,node_proxy,node_sandbox,node_linux_sandbox,node_approval toneAmber
class node_vault,node_phantom,node_privacy_shield,node_provider toneMint
class node_audit,node_report toneRose
class node_user,node_agent toneIndigo
```

## Components

### CLI workflows

- [CLI dispatch](https://github.com/hamdok/aestheris/blob/main/src/main.rs): `src/main.rs`
- [Initialize setup](https://github.com/hamdok/aestheris/blob/main/src/init.rs): `src/init.rs`
- [Exposure scan](https://github.com/hamdok/aestheris/blob/main/src/scan.rs): `src/scan.rs`
- [Project findings](https://github.com/hamdok/aestheris/blob/main/src/project_scan.rs): `src/project_scan.rs`
- [Secret detection](https://github.com/hamdok/aestheris/blob/main/src/secret.rs): `src/secret.rs`
- [Gitleaks rules](https://github.com/hamdok/aestheris/blob/main/src/gitleaks.rs): `src/gitleaks.rs`

### Gateway controls

- [Run coordinator](https://github.com/hamdok/aestheris/blob/main/src/run.rs): `src/run.rs`
- [Policy rules](https://github.com/hamdok/aestheris/blob/main/src/policy.rs): `src/policy.rs`
- [Local gateway](https://github.com/hamdok/aestheris/blob/main/src/proxy.rs): `src/proxy.rs`
- [Agent sandbox](https://github.com/hamdok/aestheris/blob/main/src/sandbox.rs): `src/sandbox.rs`
- [Linux isolation](https://github.com/hamdok/aestheris/blob/main/src/sandbox_linux.rs): `src/sandbox_linux.rs`
- [Human approval](https://github.com/hamdok/aestheris/blob/main/src/approval.rs): `src/approval.rs`

### Privacy and secrets

- [Encrypted vault](https://github.com/hamdok/aestheris/blob/main/src/vault.rs): `src/vault.rs`
- [Phantom tokens](https://github.com/hamdok/aestheris/blob/main/src/phantom.rs): `src/phantom.rs`
- [Privacy shield](https://github.com/hamdok/aestheris/blob/main/src/privacy.rs): `src/privacy.rs`

### Evidence and review

- [Audit log](https://github.com/hamdok/aestheris/blob/main/src/audit.rs): `src/audit.rs`
- [Audit reports](https://github.com/hamdok/aestheris/blob/main/src/report.rs): `src/report.rs`

### Other components

- **Developer**
- **AI agent**
- **API / model provider**

## Connections

- Developer → CLI dispatch: runs command
- CLI dispatch → Initialize setup: initializes
- CLI dispatch → Exposure scan: starts scan
- Exposure scan → Project findings: checks project
- Project findings → Secret detection: detects secrets
- Project findings → Gitleaks rules: uses rules
- CLI dispatch → Run coordinator: starts session
- Run coordinator → Policy rules: loads policy
- Run coordinator → Encrypted vault: unlocks secrets
- Run coordinator → Local gateway: starts gateway
- Run coordinator → Agent sandbox: launches agent
- Agent sandbox → Linux isolation: uses Linux isolation
- Run coordinator → Human approval: opens approval channel
- Run coordinator → Audit log: records session
- Run coordinator → AI agent: launches with phantom credentials
- AI agent → Local gateway: sends requests
- Local gateway → Policy rules: checks route rules
- Local gateway → Phantom tokens: validates token
- Local gateway → Privacy shield: filters payloads
- Local gateway → Human approval: requests decision
- Local gateway → API / model provider: forwards request
- API / model provider → Local gateway: returns response
- Local gateway → Audit log: records requests
- CLI dispatch → Human approval: handles approval command
- CLI dispatch → Audit log: reads audit events
- CLI dispatch → Audit reports: renders report
- Audit log → Audit reports: provides events