talos-protocol 3.3.9

Talos: A secure, decentralized protocol for AI Agent communication

Talos Protocol

Secure, Decentralized Communication for the AI Agent Era

🚀 Quick Start

# Clone with all submodules
git clone --recurse-submodules [e-mail]:talosprotocol/talos.git
cd talos

# Initialize and validate
./deploy/scripts/setup.sh
./deploy/scripts/run_all_tests.sh

SSH not available? The setup script auto-falls back to HTTPS.

---

📂 Repository Topology

This is a multi-repo project using git submodules:

talos/                          # Orchestrator (this repo)
├── deploy/
│   ├── repos/                  # 12 submodules
│   │   ├── talos-contracts/    # Source of truth (schemas, vectors)
│   │   ├── talos-core-rs/      # Rust performance kernel
│   │   ├── talos-sdk-py/       # Python SDK
│   │   ├── talos-sdk-ts/       # TypeScript SDK
│   │   ├── talos-sdk-go/       # Go SDK
│   │   ├── talos-sdk-java/     # Java SDK
│   │   ├── talos-gateway/      # FastAPI Gateway
│   │   ├── talos-audit-service/# Audit aggregator
│   │   ├── talos-mcp-connector/# MCP bridge
│   │   ├── talos-dashboard/    # Next.js Console
│   │   ├── talos-docs/         # Documentation wiki
│   │   └── talos-examples/     # Example applications
│   └── scripts/
│       ├── setup.sh            # Initialize submodules
│       ├── start_all.sh        # Start all services
│       ├── cleanup_all.sh      # Clean all dependencies
│       └── run_all_tests.sh    # Master test runner
└── docs/wiki/                  # Documentation (deprecated, use talos-docs)

Repo	Purpose	Tech
talos-contracts	Schemas, test vectors, helpers	TypeScript + Python
talos-core-rs	High-performance kernel	Rust + PyO3
talos-sdk-py	Python SDK	Python
talos-sdk-ts	TypeScript SDK	TypeScript
talos-sdk-go	Go SDK	Go
talos-sdk-java	Java SDK	Java
talos-gateway	REST API Gateway	FastAPI
talos-audit-service	Audit log aggregation	FastAPI
talos-mcp-connector	MCP protocol bridge	Python
talos-dashboard	Security console UI	Next.js
talos-docs	Documentation wiki	Markdown
talos-examples	Example applications	Mixed

---

📜 Contract-Driven Architecture

talos-contracts is the single source of truth. All other repos consume:

Artifact	Description
schemas/*.json	JSON Schema definitions
test_vectors/*.json	Golden test cases
src/ (TS) / talos_contracts/ (Py)	Reference implementations

Boundary Rules:

• ❌ No reimplementing deriveCursor, base64url, etc. outside contracts
• ❌ No btoa/atob in browser code (use contracts helpers)
• ❌ No deep cross-repo imports (use published packages)

---

v4.0 Features

Feature	Status	Description
📜 Contract-Driven Kernel	✅	talos-contracts as single source of truth
🔐 Capability Authorization	✅	Cryptographic tokens, <1ms session-cached auth
📦 Polyglot SDKs	✅	Native Python & TypeScript SDKs
🦀 Rust Wedge	✅	High-performance Rust core
🔄 Double Ratchet	✅	Signal protocol for forward secrecy
✅ Validation Engine	✅	5-layer block validation
💡 Light Client	✅	SPV proof verification
🤖 MCP Integration	✅	Secure tool invocation
⚡ Performance	✅	695k auth/sec, <5ms p99

---

🛠️ Development

Prerequisites

• Python 3.11+
• Node.js 20+
• Rust (stable)
• Git with SSH keys (or HTTPS fallback)

Setup Modes

Mode	Default	Behavior
lenient	Local	Warns on missing submodules, continues
strict	CI	Fails if any submodule unavailable

# Local development (lenient)
./deploy/scripts/setup.sh

# Mirror CI behavior
TALOS_SETUP_MODE=strict ./deploy/scripts/setup.sh

Service Management

# Start all services
./deploy/scripts/start_all.sh

# Stop and clean everything
./deploy/scripts/cleanup_all.sh

# Per-repo Makefile
cd deploy/repos/talos-gateway
make install build test start

Submodule Management

This project uses a pinned-SHA strategy for submodules to guarantee reproducibility.

• Strict Drift Gate: CI fails if pinned SHAs do not match the remote origin/main of the submodule.
• Automated Sync: A bot workflow runs periodically to fast-forward submodules to latest main and opens a PR.

Common Commands:

# Initialize submodules to pinned state
git submodule update --init --recursive

# Check for drift (Are my pins behind?)
./scripts/check_submodule_drift.sh

# Manually sync local submodules (updates working tree only)
git submodule foreach 'git fetch origin main && git reset --hard origin/main'

Private Repositories: If a submodule becomes private, you must ensure your CI environment and local git configuration have appropriate credentials (via SSH keys or GITHUB_TOKEN permissions), otherwise the drift check will fail.

Testing

# Run all tests (unit only)
./deploy/scripts/run_all_tests.sh

# With live integration tests
./deploy/scripts/run_all_tests.sh --with-live

# Single repo
./deploy/scripts/run_all_tests.sh --only talos-contracts

---

Dashboard & Examples

Once started, access the Security Console:

• Dashboard: http://localhost:3000
• Examples Catalog: http://localhost:3000/examples

---

📚 Documentation

Documentation is maintained in the Wiki.

Topic	Link
Getting Started	Getting Started
Architecture	Architecture
Development	Development
Testing	Testing
Python SDK	Python SDK
TypeScript SDK	TypeScript SDK
MCP Integration	MCP Integration

---

Why Talos Exists

AI agents lack a trustable communication substrate:

Problem	Current State	Talos Solution
Identity	No cryptographic identity	Self-sovereign DIDs
Authorization	Centralized OAuth/RBAC	Scoped capability tokens
Confidentiality	TLS at best	Forward secrecy (Double Ratchet)
Accountability	Trust the operator	Blockchain-anchored proofs
Decentralization	Central servers	P2P with DHT discovery

Talos is the missing trust layer for autonomous AI systems.

📖 Why Talos Wins | Threat Model | Alternatives

---

License

Licensed under the Apache License 2.0. See LICENSE.

trigger

ci