ADR-002: Karo System
| Status | Proposed |
|---|---|
| Date | December 2025 |
| Authors | Caro Maintainers |
| Supersedes | N/A |
| Related | ADR-001 (LLM Inference Architecture) |
Table of Contents
Section titled “Table of Contents”- Executive Summary
- Context and Problem Statement
- Decision Drivers
- System Mental Model
- Architecture Overview
- Node Architecture
- Distributed Mesh Architecture
- Data Flow and Schemas
- Access and Role Model
- Trust and Cryptography
- Security Considerations
- Future Direction
- Consequences
Executive Summary
Section titled “Executive Summary”This document defines Caro as a distributed terminal intelligence system designed for air-gapped and closed internal networks. Caro evolves from a single-machine CLI tool into a cooperative node network that provides:
- Individual value: Personal terminal copilot with inference, safety checks, and usage insights
- Organizational value: Aggregate visibility into terminal behavior, security posture, and operational patterns
- Zero-egress architecture: No external network communication; all data stays within the trusted network
Core Tenets:
- Local-first, mesh-optional: Each node is fully functional standalone
- Air-gap compatible: Zero internet dependencies after deployment
- Privacy-preserving aggregation: Derived insights, not raw surveillance
- Cryptographic trust: End-to-end encrypted peer communication
- Role-aware visibility: Different views for individuals, admins, and security teams
Context and Problem Statement
Section titled “Context and Problem Statement”The Evolution
Section titled “The Evolution”ADR-001 established Caro as a local-first CLI tool for command generation. This ADR extends that vision to address organizational needs:
- Individual developers want terminal intelligence without data leaving their machine
- Security teams need visibility into terminal behavior patterns across the organization
- SRE/Ops teams want to understand operational workflows and detect anomalies
- Regulated environments require air-gap compatibility and data sovereignty
The Challenge
Section titled “The Challenge”Design a system that:
- Provides immediate value on a single machine (no network required)
- Scales to organization-wide visibility when nodes are connected
- Operates entirely within closed networks (no external dependencies)
- Preserves individual privacy while enabling aggregate insights
- Requires no central infrastructure (no servers, databases, or cloud services)
Why Not Traditional Approaches?
Section titled “Why Not Traditional Approaches?”| Approach | Why Not for Caro? |
|---|---|
| Centralized logging (Splunk, ELK) | Requires infrastructure, not air-gap friendly |
| Agent-based monitoring (Datadog) | Phones home, requires internet |
| SIEM systems | Heavy infrastructure, not terminal-focused |
| Shell history sync | Raw data, no intelligence, privacy concerns |
Decision Drivers
Section titled “Decision Drivers”Primary Drivers
Section titled “Primary Drivers”- Air-Gap First: Must work in networks with zero internet connectivity
- No Central Infrastructure: No servers, databases, or coordination points required
- Privacy Gradient: Individual data stays local; only consented summaries are shared
- Standalone Value: Single node must be fully useful without mesh
- Cryptographic Security: All inter-node communication encrypted
Secondary Drivers
Section titled “Secondary Drivers”- Minimal resource footprint on individual machines
- Graceful degradation when nodes are unreachable
- Support for heterogeneous environments (macOS, Linux, various shells)
- Auditability of what data is shared
System Mental Model
Section titled “System Mental Model”Caro operates as four simultaneous identities:
┌─────────────────────────────────────────────────────────────────────┐│ CARO NODE IDENTITY │├─────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ ││ │ TERMINAL │ │ LOCAL │ │ DISTRIBUTED │ ││ │ COPILOT │ │ OBSERVABILITY │ │ INTELLIGENCE │ ││ │ │ │ AGENT │ │ NODE │ ││ │ • NL→Command │ │ │ │ │ ││ │ • Safety check │ │ • Shell history│ │ • Mesh participant │ ││ │ • Context help │ │ • Process watch│ │ • Encrypted relay │ ││ │ │ │ • Usage patterns│ │ • Aggregate views │ ││ └─────────────────┘ └─────────────────┘ └─────────────────────┘ ││ ││ ┌─────────────────────────────────────────────────────────────────┐││ │ ZERO-EGRESS SECURITY SYSTEM │││ │ │││ │ • Never communicates outside internal network │││ │ • All external model inference is local │││ │ • Cryptographic identity per node │││ └─────────────────────────────────────────────────────────────────┘│└─────────────────────────────────────────────────────────────────────┘Architecture Overview
Section titled “Architecture Overview”Layered System Design
Section titled “Layered System Design”┌─────────────────────────────────────────────────────────────────────┐│ PRESENTATION LAYER │├──────────────────┬──────────────────┬───────────────────────────────┤│ CLI Interface │ Local Dashboard │ Mesh Dashboard ││ (Terminal) │ (localhost:9237)│ (Role-Based Views) │└──────────────────┴──────────────────┴───────────────────────────────┘ │┌─────────────────────────────────────────────────────────────────────┐│ APPLICATION LAYER │├──────────────────┬──────────────────┬───────────────────────────────┤│ Inference │ Observation │ Aggregation ││ Engine │ Engine │ Engine ││ (ADR-001) │ │ ││ │ • Shell watcher │ • Local summaries ││ • Command gen │ • Process mon │ • Cross-node queries ││ • Safety check │ • Context track │ • Pattern detection ││ • Risk assess │ • Event log │ • Anomaly alerts │└──────────────────┴──────────────────┴───────────────────────────────┘ │┌─────────────────────────────────────────────────────────────────────┐│ DATA LAYER │├──────────────────────────────────────────────────────────────────────┤│ Local Storage │ Mesh Communication ││ • SQLite event store │ • Peer discovery ││ • Command history │ • Encrypted channels ││ • Inference cache │ • Summary exchange ││ • Configuration │ • Query routing │└─────────────────────────────────────┴───────────────────────────────┘ │┌─────────────────────────────────────────────────────────────────────┐│ PLATFORM LAYER │├──────────────────────────────────────────────────────────────────────┤│ • Shell integration (bash, zsh, fish) ││ • Process observation (procfs, sysctl) ││ • Network stack (TCP/TLS internal only) ││ • Cryptographic primitives (ring, rustls) │└─────────────────────────────────────────────────────────────────────┘Node Architecture
Section titled “Node Architecture”Single Node Components
Section titled “Single Node Components”┌─────────────────────────────────────────────────────────────────────┐│ CARO NODE │├─────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ CLI AGENT (Terminal) │ ││ │ caro "list all files modified today" │ ││ │ caro --explain "what does this awk command do?" │ ││ │ caro --history │ ││ └─────────────────────────────────────────────────────────────┘ ││ │ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ BACKGROUND SERVICE │ ││ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ ││ │ │Shell Watcher │ │Process Mon │ │ Event Processor │ │ ││ │ │ │ │ │ │ │ │ ││ │ │• Hook into │ │• Track child │ │• Categorize events │ │ ││ │ │ shell │ │ processes │ │• Extract patterns │ │ ││ │ │• Capture │ │• Monitor │ │• Generate summaries │ │ ││ │ │ commands │ │ resources │ │• Detect anomalies │ │ ││ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ ││ └─────────────────────────────────────────────────────────────┘ ││ │ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ LOCAL WEB SERVER │ ││ │ http://localhost:9237 │ ││ │ • Personal dashboard │ ││ │ • Usage analytics │ ││ │ • Mesh status (if connected) │ ││ └─────────────────────────────────────────────────────────────┘ ││ │ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ LOCAL DATA STORE │ ││ │ ~/.local/share/caro/ │ ││ │ ├── events.db # SQLite event store │ ││ │ ├── config.toml # Node configuration │ ││ │ ├── identity.key # Node cryptographic identity │ ││ │ └── cache/ # Inference & model cache │ ││ └─────────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────────┘Observation Scope
Section titled “Observation Scope”What a Caro node observes on its machine:
| Category | Data Collected | Purpose |
|---|---|---|
| Shell Commands | Command text, exit codes, duration | Usage patterns, failure analysis |
| Working Context | cwd, shell type, user, privileges | Context-aware assistance |
| Process Tree | Child processes of terminal | Understanding command effects |
| Caro Interactions | Generated commands, user prompts | Quality improvement, usage stats |
| Timestamps | When commands executed | Temporal patterns |
What a Caro node never collects:
- File contents (only paths if part of command)
- Network traffic or connections
- Keystrokes outside of commands
- Screen contents or clipboard
- Other applications’ data
Distributed Mesh Architecture
Section titled “Distributed Mesh Architecture”Peer-to-Peer Topology
Section titled “Peer-to-Peer Topology”┌─────────────────────────────────────────────────────────────────────┐│ CARO MESH (Internal Network) │├─────────────────────────────────────────────────────────────────────┤│ ││ ┌───────────┐ ┌───────────┐ ┌───────────┐ ││ │ Node A │◄───────►│ Node B │◄───────►│ Node C │ ││ │ (Dev 1) │ │ (Dev 2) │ │ (SRE 1) │ ││ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ ││ │ │ │ ││ │ ┌───────────┐ │ │ ││ └───►│ Node D │◄───┘ │ ││ │ (Admin) │◄─────────────────────────┘ ││ └─────┬─────┘ ││ │ ││ ▼ ││ ┌───────────────┐ ││ │ Node E │ ││ │ (CISO) │ ││ │ │ ││ │ Aggregate │ ││ │ Dashboard │ ││ └───────────────┘ ││ ││ Legend: ││ ◄──────► Encrypted peer connection ││ All connections are bidirectional, E2E encrypted ││ No central server - any node can query the mesh ││ │└─────────────────────────────────────────────────────────────────────┘Mesh Properties
Section titled “Mesh Properties”- Decentralized: No coordinator, leader, or central server
- Eventually Consistent: Summaries propagate through gossip
- Partition Tolerant: Nodes work independently if isolated
- Encrypted: All inter-node traffic uses TLS 1.3 with mutual auth
- Opt-In: Nodes choose what to share via sharing policies
Node Discovery
Section titled “Node Discovery”Within closed networks, nodes discover each other via:
| Method | How It Works | Configuration |
|---|---|---|
| Static Config | Explicit list of peer addresses | peers = ["10.0.0.5:9238", "10.0.0.6:9238"] |
| Subnet Scan | Probe known port on subnet | discovery.subnet = "10.0.0.0/24" |
| mDNS/Bonjour | Multicast DNS service discovery | discovery.mdns = true |
| DNS-SD | DNS service records in internal DNS | discovery.dns_sd = "_caro._tcp.internal.corp" |
Default: Static config + optional mDNS (zero external dependencies).
Data Flow and Schemas
Section titled “Data Flow and Schemas”Data Categories
Section titled “Data Categories”┌─────────────────────────────────────────────────────────────────────┐│ DATA CLASSIFICATION │├─────────────────────────────────────────────────────────────────────┤│ ││ LEVEL 0: RAW (Never leaves node) ││ ├── Full command text with arguments ││ ├── File paths and contents ││ ├── Environment variables ││ └── User prompts to Caro ││ ││ LEVEL 1: SUMMARIZED (Shared with explicit consent) ││ ├── Command patterns (e.g., "git operations: 45/day") ││ ├── Tool usage frequencies ││ ├── Temporal patterns (e.g., "peak activity: 10-11am") ││ └── Risk event counts (e.g., "3 high-risk commands blocked") ││ ││ LEVEL 2: AGGREGATED (Mesh-wide visibility) ││ ├── Organization-wide tool adoption ││ ├── Cross-team workflow patterns ││ ├── Anomaly detection signals ││ └── Security posture metrics ││ │└─────────────────────────────────────────────────────────────────────┘Core Data Schemas
Section titled “Core Data Schemas”Node Identity
Section titled “Node Identity”/// Cryptographic identity of a Caro nodestruct NodeIdentity { /// Ed25519 public key (32 bytes, base64 encoded) public_key: String,
/// Human-readable node name (optional) display_name: Option<String>,
/// Node capabilities and version capabilities: NodeCapabilities,
/// First seen timestamp (by this node) first_seen: DateTime<Utc>,
/// Trust level assigned by local policy trust_level: TrustLevel,}
struct NodeCapabilities { /// Protocol version protocol_version: u32,
/// Caro version caro_version: String,
/// Supported sharing levels supports_level1: bool, supports_level2: bool,
/// Whether node can serve aggregate queries can_aggregate: bool,}
enum TrustLevel { /// Not trusted, no data exchange Untrusted, /// Can receive our summaries ShareTo, /// Can query our summaries QueryFrom, /// Full bidirectional trust Peer, /// Can see all mesh data (admin/CISO) Supervisor,}Terminal Event
Section titled “Terminal Event”/// A single terminal event (Level 0 - never shared)struct TerminalEvent { /// Unique event ID id: Uuid,
/// When the command was executed timestamp: DateTime<Utc>,
/// The shell type shell: ShellType,
/// Full command text command: String,
/// Working directory cwd: PathBuf,
/// Exit code (if completed) exit_code: Option<i32>,
/// Duration in milliseconds duration_ms: Option<u64>,
/// Was this command generated by Caro? caro_generated: bool,
/// Safety assessment risk_level: RiskLevel,
/// Was user confirmation required? required_confirmation: bool,}
enum ShellType { Bash, Zsh, Fish, Sh, Other(String),}
enum RiskLevel { Safe, Moderate, High, Critical,}Node Summary (Level 1)
Section titled “Node Summary (Level 1)”/// Summarized data that can be shared with peersstruct NodeSummary { /// Summary period period: SummaryPeriod,
/// Node identity node_id: String, // Public key fingerprint
/// Command pattern statistics command_patterns: Vec<PatternStat>,
/// Tool usage frequencies tool_usage: HashMap<String, u32>,
/// Temporal activity pattern activity_pattern: ActivityPattern,
/// Safety statistics safety_stats: SafetyStats,
/// Generated at timestamp generated_at: DateTime<Utc>,
/// Cryptographic signature signature: String,}
struct SummaryPeriod { start: DateTime<Utc>, end: DateTime<Utc>, granularity: Granularity,}
enum Granularity { Hourly, Daily, Weekly,}
struct PatternStat { /// Pattern category (e.g., "git", "docker", "file-ops") category: String,
/// Count in period count: u32,
/// Average duration (ms) avg_duration_ms: u32,
/// Failure rate (0.0 - 1.0) failure_rate: f32,}
struct ActivityPattern { /// Commands per hour bucket (24 entries) hourly_distribution: [u32; 24],
/// Commands per day of week (7 entries) daily_distribution: [u32; 7],
/// Total commands in period total_commands: u32,
/// Unique command count unique_commands: u32,}
struct SafetyStats { /// Commands by risk level by_risk_level: HashMap<RiskLevel, u32>,
/// Blocked commands count blocked_count: u32,
/// User-confirmed risky commands confirmed_risky: u32,
/// Caro-generated commands caro_generated: u32,}Mesh Query
Section titled “Mesh Query”/// Query sent to mesh for aggregate datastruct MeshQuery { /// Query ID for correlation query_id: Uuid,
/// Requesting node identity requester: String,
/// Query type query_type: QueryType,
/// Time range time_range: TimeRange,
/// Optional filters filters: Vec<QueryFilter>,
/// Signature proving identity signature: String,}
enum QueryType { /// Get aggregated tool usage across mesh ToolUsage,
/// Get safety posture metrics SafetyPosture,
/// Get activity patterns ActivityPatterns,
/// Get anomaly signals Anomalies,
/// Get node health status NodeHealth,}
struct QueryFilter { field: String, operator: FilterOp, value: String,}
enum FilterOp { Equals, Contains, GreaterThan, LessThan,}Mesh Response
Section titled “Mesh Response”/// Response to a mesh querystruct MeshResponse { /// Correlation ID query_id: Uuid,
/// Responding node responder: String,
/// Response data (varies by query type) data: ResponseData,
/// Nodes that contributed to this response contributing_nodes: Vec<String>,
/// Response timestamp timestamp: DateTime<Utc>,
/// Signature signature: String,}
enum ResponseData { ToolUsage(AggregatedToolUsage), SafetyPosture(AggregatedSafetyPosture), ActivityPatterns(AggregatedActivityPatterns), Anomalies(Vec<AnomalySignal>), NodeHealth(Vec<NodeHealthStatus>),}Access and Role Model
Section titled “Access and Role Model”Role Hierarchy
Section titled “Role Hierarchy”┌─────────────────────────────────────────────────────────────────────┐│ ROLE HIERARCHY │├─────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ INDIVIDUAL CONTRIBUTOR │ ││ │ • Full access to own node data (Level 0-2) │ ││ │ • Personal dashboard │ ││ │ • Own usage analytics │ ││ │ • Controls what is shared │ ││ └─────────────────────────────────────────────────────────────┘ ││ │ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ TEAM LEAD / SYSADMIN │ ││ │ • Level 1-2 data from team nodes (consented) │ ││ │ • Team aggregate dashboard │ ││ │ • Tool adoption metrics │ ││ │ • Cannot see raw commands │ ││ └─────────────────────────────────────────────────────────────┘ ││ │ ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ SECURITY TEAM / CISO │ ││ │ • Level 2 data from all nodes (by policy) │ ││ │ • Organization-wide security posture │ ││ │ • Anomaly detection dashboard │ ││ │ • Risk trend analysis │ ││ │ • Cannot see raw commands (only patterns) │ ││ └─────────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────────┘Access Without Central Server
Section titled “Access Without Central Server”In a serverless mesh, access is granted by:
- Direct Connection: User installs Caro on their machine, connects to mesh
- Query Routing: Their node routes queries through the mesh
- Policy Enforcement: Each responding node enforces its sharing policy
- Result Aggregation: Requesting node aggregates responses
┌──────────────┐ Query ┌──────────────┐│ CISO │ ───────────────►│ Node A ││ Node │ │ ││ │ │ (checks ││ │ │ policy: ││ │ │ CISO=allow) ││ │◄─────────────── │ ││ │ Level 2 data └──────────────┘│ ││ │ Query ┌──────────────┐│ │ ───────────────►│ Node B ││ │ │ (policy: OK) ││ │◄─────────────── │ ││ │ Level 2 data └──────────────┘│ ││ │ Query ┌──────────────┐│ │ ───────────────►│ Node C ││ │ │ (policy: ││ │ │ CISO=deny) ││ │◄─────────────── │ ││ │ ACCESS DENIED └──────────────┘│ ││ Aggregate ││ A + B │└──────────────┘Sharing Policies
Section titled “Sharing Policies”Each node defines its sharing policy:
[sharing]# What level of data to sharemax_level = 2 # 0=none, 1=summaries, 2=aggregated
# Who can query this node (by public key or role)[sharing.allow]peers = ["*"] # Allow all trusted peerssupervisors = ["fingerprint:abc123..."] # Specific CISO key
# What categories to share[sharing.categories]tool_usage = trueactivity_patterns = truesafety_stats = trueanomalies = true
# Explicit denials override allows[sharing.deny]# Don't share with untrusted nodesuntrusted = trueTrust and Cryptography
Section titled “Trust and Cryptography”Cryptographic Primitives
Section titled “Cryptographic Primitives”| Purpose | Algorithm | Implementation |
|---|---|---|
| Node Identity | Ed25519 | ring crate |
| Key Exchange | X25519 | ring crate |
| Transport | TLS 1.3 | rustls |
| Symmetric Encryption | ChaCha20-Poly1305 | ring crate |
| Hashing | BLAKE3 | blake3 crate |
| Key Derivation | HKDF-SHA256 | ring crate |
Identity Model
Section titled “Identity Model”┌─────────────────────────────────────────────────────────────────────┐│ NODE IDENTITY LIFECYCLE │├─────────────────────────────────────────────────────────────────────┤│ ││ 1. GENERATION (First Run) ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Ed25519 keypair generated │ ││ │ Private key stored: ~/.local/share/caro/identity.key │ ││ │ Public key = Node ID (base64: "caro:ed25519:Abc123...") │ ││ │ Fingerprint = BLAKE3(public_key)[0:8] (for display) │ ││ └─────────────────────────────────────────────────────────┘ ││ ││ 2. PEER INTRODUCTION ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Node A ──► "Hello, I am caro:ed25519:Abc123" │ ││ │ Node B ──► "Hello, I am caro:ed25519:Def456" │ ││ │ Both perform X25519 key agreement for session key │ ││ │ TLS 1.3 channel established with mutual authentication │ ││ └─────────────────────────────────────────────────────────┘ ││ ││ 3. TRUST ESTABLISHMENT ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Option A: Pre-shared trust (config file) │ ││ │ [peers.trusted] │ ││ │ "caro:ed25519:Def456" = { name = "Bob", role = "dev" }│ ││ │ │ ││ │ Option B: TOFU (Trust On First Use) with confirmation │ ││ │ "New peer detected: Def456. Trust? [y/N]" │ ││ │ │ ││ │ Option C: Certificate chain (enterprise deployment) │ ││ │ Organization root CA signs node certificates │ ││ └─────────────────────────────────────────────────────────┘ ││ ││ 4. KEY ROTATION ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Nodes can rotate keys while maintaining identity │ ││ │ Old key signs endorsement of new key │ ││ │ Grace period for peers to learn new key │ ││ └─────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────────┘Trust Domains
Section titled “Trust Domains”For enterprise deployment, trust can be scoped by domain:
[trust.domains]# Engineering teamengineering = { subnet = "10.0.1.0/24", role = "peer" }
# Security team (supervisor access)security = { subnet = "10.0.2.0/24", role = "supervisor" }
# External contractors (no mesh access)contractors = { subnet = "10.0.3.0/24", role = "untrusted" }Message Authentication
Section titled “Message Authentication”All inter-node messages are signed:
struct SignedMessage<T> { /// The payload payload: T,
/// Sender's node ID sender: String,
/// Timestamp (prevents replay) timestamp: DateTime<Utc>,
/// Nonce (prevents replay) nonce: [u8; 16],
/// Ed25519 signature over (payload || sender || timestamp || nonce) signature: [u8; 64],}Replay Protection
Section titled “Replay Protection”- Timestamps: Messages older than 5 minutes are rejected
- Nonces: Recent nonces are cached; duplicates rejected
- Sequence Numbers: Long-lived connections use monotonic sequence numbers
Security Considerations
Section titled “Security Considerations”Threat Model
Section titled “Threat Model”| Threat | Mitigation |
|---|---|
| Network eavesdropping | TLS 1.3 encryption on all channels |
| Node impersonation | Ed25519 signatures on all messages |
| Replay attacks | Timestamps + nonces + sequence numbers |
| Unauthorized access | Role-based policies, cryptographic identity |
| Data exfiltration | No external network access, Level 0 never shared |
| Compromised node | Can only share its own data; cannot forge others’ |
| Key compromise | Key rotation supported; revocation via trust removal |
Defense in Depth
Section titled “Defense in Depth”┌─────────────────────────────────────────────────────────────────────┐│ SECURITY LAYERS │├─────────────────────────────────────────────────────────────────────┤│ ││ Layer 1: Network Isolation ││ └── Caro only binds to internal interfaces ││ └── Firewall rules can further restrict mesh ports ││ ││ Layer 2: Transport Security ││ └── TLS 1.3 with mutual authentication ││ └── Certificate pinning for known peers ││ ││ Layer 3: Message Security ││ └── All messages signed by sender ││ └── Replay protection via timestamp/nonce ││ ││ Layer 4: Access Control ││ └── Role-based query permissions ││ └── Per-node sharing policies ││ ││ Layer 5: Data Classification ││ └── Level 0 data never leaves node ││ └── Only derived/summarized data shared ││ │└─────────────────────────────────────────────────────────────────────┘Audit Trail
Section titled “Audit Trail”Every mesh operation is logged locally:
struct AuditEvent { timestamp: DateTime<Utc>, event_type: AuditEventType, peer: Option<String>, details: String, success: bool,}
enum AuditEventType { PeerConnected, PeerDisconnected, QueryReceived, QueryResponded, PolicyViolation, TrustChange, KeyRotation,}Future Direction
Section titled “Future Direction”Short-Term (6 months)
Section titled “Short-Term (6 months)”- Core Implementation: Background service, shell integration, local dashboard
- Peer Discovery: Static config, mDNS support
- Basic Mesh: Summary exchange between trusted peers
- CLI Dashboard:
caro dashboardopens local web UI
Medium-Term (12 months)
Section titled “Medium-Term (12 months)”- Aggregate Views: Cross-node query routing and aggregation
- Anomaly Detection: Pattern-based unusual activity detection
- Policy Engine: Fine-grained sharing controls
- Enterprise Deployment: Configuration management, certificate chain trust
Long-Term Vision
Section titled “Long-Term Vision”- Reactive Agents: Real-time intervention for risky commands
- Continuous Learning: Organization-specific pattern learning
- Policy-Aware Inference: Commands aligned with internal standards
- Compliance Reporting: Automated security posture reports
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Air-Gap Compatible: Works in most secure environments
- No Infrastructure: No servers to deploy or maintain
- Privacy Preserving: Raw data never leaves the machine
- Individually Useful: Full value even without mesh
- Cryptographically Secure: Strong authentication and encryption
- Auditable: Complete local audit trail
Negative
Section titled “Negative”- Complexity: Significant increase over single-node CLI
- Resource Usage: Background service consumes memory
- Network Configuration: Mesh requires network access between nodes
- Trust Management: Peer trust needs initial configuration
- Eventual Consistency: No real-time global view
- Discovery Reliability: mDNS may not work in all network environments
- Key Management: Lost identity keys require re-establishing trust
- Policy Drift: Nodes may have inconsistent sharing policies
- Query Performance: Large meshes may have slow aggregate queries
Mitigations
Section titled “Mitigations”- Multiple Discovery Methods: Static config as reliable fallback
- Key Backup: Optional encrypted key backup
- Policy Templates: Organization-wide policy distribution
- Query Caching: Cache aggregate results with TTL
Appendix A: Protocol Wire Format
Section titled “Appendix A: Protocol Wire Format”Messages between nodes use a simple framed format:
┌─────────────────────────────────────────────────────────────────┐│ Magic (4 bytes) │ Version (2) │ Length (4) │ Type (2) │├─────────────────────────────────────────────────────────────────┤│ Payload (variable) │├─────────────────────────────────────────────────────────────────┤│ Signature (64 bytes) │└─────────────────────────────────────────────────────────────────┘
Magic: 0x4B41524F ("CARO")Version: Protocol version (currently 1)Length: Payload length in bytesType: Message type enumPayload: MessagePack-encoded message bodySignature: Ed25519 signature over (Version || Length || Type || Payload)Appendix B: Dashboard Mockups
Section titled “Appendix B: Dashboard Mockups”Individual Dashboard
Section titled “Individual Dashboard”┌─────────────────────────────────────────────────────────────────┐│ CARO - Personal Terminal Intelligence localhost:9237 │├─────────────────────────────────────────────────────────────────┤│ ││ Today's Activity Command Categories ││ ───────────────── ────────────────── ││ Commands: 127 ████████ git (45) ││ Caro-generated: 23 ██████ docker (32) ││ Risky (blocked): 2 █████ kubectl (28) ││ Avg duration: 1.2s ███ npm (15) ││ ██ other (7) ││ ││ Recent Commands (sanitized) ││ ─────────────────────────── ││ 10:32 | git commit -m "..." | ✓ Safe ││ 10:31 | docker build . | ✓ Safe ││ 10:28 | rm -rf node_modules/ | ⚠ Moderate (confirmed) ││ 10:25 | kubectl get pods | ✓ Safe ││ ││ Mesh Status: Connected (4 peers) ││ │└─────────────────────────────────────────────────────────────────┘Security Dashboard (CISO View)
Section titled “Security Dashboard (CISO View)”┌─────────────────────────────────────────────────────────────────┐│ CARO - Organization Security Posture │├─────────────────────────────────────────────────────────────────┤│ ││ Mesh Health Risk Distribution ││ ─────────── ───────────────── ││ Nodes Online: 42/45 ████████████ Safe (89%) ││ Last 24h Queries: 1,247 ███ Moderate (8%) ││ Avg Response: 45ms █ High (2%) ││ ░ Critical (1%) ││ ││ Anomaly Signals (Last 7 Days) ││ ───────────────────────────── ││ ⚠ Node eng-042: Unusual rm patterns (3 incidents) ││ ⚠ Subnet 10.0.3.x: High failure rate (15% vs 2% baseline) ││ ✓ No privilege escalation attempts detected ││ ││ Tool Adoption Trends ││ ──────────────────── ││ kubectl: ▲ 23% (security training impact?) ││ docker: ─ stable ││ legacy-script.sh: ▼ 45% (migration successful) ││ │└─────────────────────────────────────────────────────────────────┘Appendix C: Related Documents
Section titled “Appendix C: Related Documents”This ADR was authored in December 2025 and represents the target architecture for Caro as a distributed terminal intelligence system. Implementation will proceed in phases as defined in the Future Direction section.