Lango 🐿️

Early-stage project. Some features are experimental and may change between releases.
See the feature status table for stability details.

A trustworthy multi-agent runtime in Go. Lango is a high-performance agent runtime that lets AI agents collaborate, learn, and operate autonomously — with built-in observability, security hardening, and an optional peer-to-peer economy layer.

Why Lango?

Most agent frameworks stop at tool-calling. Lango builds a trustworthy operational foundation — then optionally extends into a peer-to-peer economy:

• Multi-Agent Orchestration — Hierarchical sub-agent teams with role-based delegation, P2P team coordination with conflict resolution strategies, and DAG-based workflow pipelines.
• Production Observability — Token usage tracking, Prometheus metrics, OpenTelemetry tracing, health monitoring, alerting with webhook delivery, and audit logging.
• Zero-Knowledge Security — ZK proofs (Plonk/Groth16) for handshake authentication and response attestation. Agents prove identity and output integrity without revealing internals. Hardware keyring and Cloud KMS support.
• Knowledge as Currency — Self-learning knowledge graph, observational memory, and hybrid vector + graph RAG retrieval — agents that get smarter with every interaction can charge for their expertise.
• Open Interoperability — A2A protocol for remote agent discovery, MCP integration for external tool servers, and multi-provider AI support (OpenAI, Anthropic, Gemini, Ollama).
• Peer-to-Peer Agent Economy — Agents discover, authenticate, negotiate prices, and trade capabilities over libp2p with budget management, trust-based risk assessment, and dynamic pricing. No central hub. No vendor lock-in.
• On-Chain Settlement — USDC payments on Base Sepolia testnet (chainId 84532) with EIP-3009 authorization, milestone-based escrow (Hub/Vault dual-mode), Foundry smart contracts, and a Security Sentinel that detects anomalies in real time.
• Smart Accounts — ERC-7579 modular smart accounts (Safe-based) with ERC-4337 account abstraction, hierarchical session keys, gasless USDC transactions via paymaster, and on-chain spending limits.
• Trust & Reputation — Every interaction builds a verifiable reputation score. Trusted peers get post-pay terms and price discounts; new peers prepay or use escrow.

Single binary. <100ms startup. <250MB memory. Just Go.

Features

• 🔥 Fast - Single binary, <100ms startup, <250MB memory
• 🤖 Multi-Provider AI - OpenAI, Anthropic, Gemini, Ollama with unified interface
• 🔌 Multi-Channel - Telegram, Discord, Slack support
• 🛠️ Rich Tools - Shell execution, file system operations, browser automation, crypto & secrets tools
• 🧠 Self-Learning - Knowledge store, learning engine, file-based skill system with GitHub import (git clone + HTTP fallback), observational memory, proactive knowledge librarian
• 📊 Knowledge Graph & Graph RAG - BoltDB triple store with hybrid vector + graph retrieval
• 🔀 Multi-Agent Orchestration - Hierarchical sub-agents (operator, navigator, vault, librarian, automator, planner, chronicler, ontologist)
• 🌍 A2A Protocol - Agent-to-Agent protocol for remote agent discovery and integration
• 🌐 P2P Network - Decentralized agent-to-agent connectivity via libp2p with DHT discovery, ZK-enhanced handshake, knowledge firewall, and peer payments
• 💸 Blockchain Payments - USDC payments on Base L2, X402 V2 auto-pay protocol (Coinbase SDK), spending limits
• ⏰ Cron Scheduling - Persistent cron jobs with cron/interval/one-time schedules, multi-channel delivery
• ⚡ Background Execution - Async task manager with concurrency control and completion notifications
• 🔄 Workflow Engine - DAG-based YAML workflows with parallel step execution and state persistence
• 🔗 MCP Integration - Connect to external MCP servers (stdio/HTTP/SSE), auto-discovery, health checks, multi-scope config
• 🔒 Secure - Master Key envelope (MK/KEK hierarchy), AES-256-GCM encryption, recovery mnemonic, key registry, secret management, output scanning, hardware keyring (Touch ID / TPM), SQLCipher DB encryption, Cloud KMS (AWS/GCP/Azure/PKCS#11)
• 💾 Persistent - Ent ORM with SQLite session storage
• 🌐 Gateway - WebSocket/HTTP server with real-time streaming
• 🔑 Auth - OIDC authentication, OAuth login flow
• 🏗️ Agent Registry - Custom agent definitions via AGENT.md files, dynamic routing with keyword + capability matching
• 🧬 Agent Memory - Per-agent persistent memory for cross-session context retention
• 📡 Event Bus - Typed synchronous pub/sub for internal component communication
• 🪝 Tool Hooks - Middleware chain for tool execution (security filter, access control, event publishing, knowledge save)
• 🏊 Agent Pool - P2P agent pool with health checking and weighted selection
• 💰 P2P Settlement - On-chain USDC settlement with EIP-3009, receipt tracking, and retry
• 💰 P2P Economy — Budget management, trust-based risk assessment, dynamic pricing with peer discounts, P2P negotiation protocol, and milestone-based escrow with on-chain Hub/Vault dual-mode settlement
• 🛡️ Security Sentinel — Real-time anomaly detection for on-chain escrow (rapid creation, large withdrawal, repeated dispute, unusual timing, balance drop)
• 📜 Smart Contracts — EVM smart contract interaction with ABI caching, view/pure reads, state-changing calls, and Foundry-based escrow contracts (LangoEscrowHub, LangoVault, LangoVaultFactory)
• 🏦 Smart Accounts — ERC-7579 modular smart accounts (Safe-based), ERC-4337 account abstraction with session keys, gasless USDC transactions via paymaster (Circle/Pimlico/Alchemy), on-chain spending limits, and hierarchical session key management
• 👥 P2P Teams — Task-scoped agent groups with role-based delegation, conflict resolution (trust_weighted, majority_vote, leader_decides, fail_on_conflict), assignment strategies, and payment coordination
• 📊 Observability — Token usage tracking, health monitoring, audit logging, and metrics endpoints
• 🎯 Context Engineering — Token-budget-aware context allocation, retrieval coordinator (FactSearch + TemporalSearch + ContextSearch), config profiles (off/lite/balanced/full), and relevance score auto-adjustment
• 🖥️ Cockpit TUI — Multi-panel terminal dashboard with 7 pages (Chat, Settings, Tools, Status, Sessions, Tasks, Approvals). Context panel with live token usage, tool stats, runtime, channels, and system metrics. Two-tier approval with inline strip and fullscreen dialog. Background task management with detail view, cancel, and retry. Runtime visibility with delegation tracking, budget warnings, and recovery events
• 📋 RunLedger (Task OS) — Durable execution engine with append-only journal, PEV verification, typed validators, and planner integration
• 📜 Session Provenance — Persistent checkpoints, session lineage tree, git-aware attribution, and signed provenance bundle export/import
• 🛡️ OS-level Sandbox — Process isolation via macOS Seatbelt and Linux bubblewrap (when bwrap is installed), network deny, workspace-scoped write access, automatic control-plane (~/.lango) and .git masking (walks up to the repo root and follows linked-worktree pointers), file-level deny via /dev/null bind, symlink resolution, glob patterns in deny/write lists, audit trail of every apply/skip/exclude decision
• 🚧 Response Gatekeeper — Output sanitization stripping thought tags, internal markers, raw JSON, and custom patterns

Quick Start

Installation

# Build from source
git clone https://github.com/langoai/lango.git
cd lango
make build

# Or install directly
go install github.com/langoai/lango/cmd/lango@latest

Configuration

All configuration is stored in an encrypted SQLite database (~/.lango/lango.db), protected by a passphrase (AES-256-GCM). No plaintext config files are stored on disk.

Use the guided onboard wizard for first-time setup:

lango onboard

Run

lango serve

# Validate configuration
lango config validate

The onboard wizard guides you through 5 steps:

1. Provider Setup — Choose an AI provider and enter API credentials
2. Agent Config — Select model, max tokens, and temperature
3. Channel Setup — Configure Telegram, Discord, or Slack
4. Security & Auth — Enable privacy interceptor and PII protection
5. Test Config — Validate your configuration

For the full configuration editor with all options, use lango settings.

CLI Commands

See the full CLI Reference for the complete command set.

lango                            Launch cockpit TUI (interactive terminal)
lango cockpit                    Launch multi-panel TUI dashboard
lango serve                      Start the gateway server
lango chat                       Launch plain chat TUI
lango onboard                    Guided 5-step setup wizard
lango settings                   Full interactive configuration editor
lango doctor [--fix]             Diagnostics and health checks
lango status [--output json]     Unified system status dashboard

Diagnostics

Run the doctor command to check your setup:

# Check configuration and environment
lango doctor

# Auto-fix common issues
lango doctor --fix

# JSON output for scripting
lango doctor --json

Cockpit TUI

The cockpit is a multi-panel terminal dashboard launched via lango or lango cockpit. It provides real-time visibility into agent operations with a sidebar, context panel, and 7 switchable pages:

Context Panel (Ctrl+P) — Right-side panel with 5 live sections: token usage, tool stats, runtime status, channel status, and system uptime.

Two-Tier Approval — Inline strip for safe operations and fullscreen dialog with diff preview for dangerous tools, integrated into the Chat page.

Runtime Visibility — Context panel shows delegation tracking, per-turn token summary, and active agent indicator during multi-agent turns. Recovery events surface as in-chat notifications.

Background Tasks — Tasks page with table view, detail expansion (Enter), cancel (c), and retry (r) for failed/cancelled tasks.

Additional shortcuts: Ctrl+B (toggle sidebar), Tab (switch focus), Ctrl+Y (copy to clipboard).

See Cockpit Reference, Approval Guide, Task Management Guide, Channel Integration Guide, and Troubleshooting for full documentation.

Architecture

lango/
├── cmd/lango/              # CLI entry point (cobra)
├── internal/
│   ├── adk/                # Google ADK agent wrapper, session/state adapters
│   ├── agent/              # Agent types, PII redactor, secret scanner
│   ├── agentmemory/        # Per-agent persistent memory store
│   ├── agentregistry/      # Agent definition registry with AGENT.md loading
│   ├── app/                # Application bootstrap, wiring, tool registration
│   ├── appinit/            # Module system with topological dependency sort
│   ├── approval/           # Composite approval provider for sensitive tools
│   ├── asyncbuf/           # Generic async batch processor
│   ├── bootstrap/          # Application bootstrap: DB, crypto, config profile init
│   ├── dbmigrate/          # Database encryption migration (SQLCipher)
│   ├── channels/           # Telegram, Discord, Slack integrations
│   ├── cli/                # CLI commands
│   │   ├── tuicore/        #   Shared TUI components (FormModel, Field types)
│   │   ├── clitypes/       #   Shared CLI type definitions (provider loaders)
│   │   ├── a2a/            #   lango a2a card/check
│   │   ├── agent/          #   lango agent status/list/tools/hooks
│   │   ├── approval/       #   lango approval status
│   │   ├── bg/             #   lango bg list/status/cancel/result
│   │   ├── chat/           #   lango chat (plain TUI chat)
│   │   ├── cliboot/        #   Shared CLI bootstrap / lazy config loading
│   │   ├── cockpit/        #   lango cockpit (multi-panel TUI dashboard)
│   │   ├── configcmd/      #   lango config list/create/use/delete/import/export/validate/get/set/keys
│   │   ├── contract/       #   lango contract read/call/abi
│   │   ├── cron/           #   lango cron add/list/delete/pause/resume/history
│   │   ├── doctor/         #   lango doctor (diagnostics)
│   │   ├── economy/        #   lango economy budget/risk/pricing/negotiate/escrow status/list/show/sentinel
│   │   ├── graph/          #   lango graph status/query/stats/clear
│   │   ├── learning/       #   lango learning status/history
│   │   ├── librarian/      #   lango librarian status/inquiries
│   │   ├── mcp/            #   lango mcp list/add/remove/get/test/enable/disable
│   │   ├── memory/         #   lango memory list/status/clear
│   │   ├── metrics/        #   lango metrics [sessions|tools|agents|history]
│   │   ├── onboard/        #   lango onboard (5-step guided wizard)
│   │   ├── p2p/            #   lango p2p status/peers/connect/disconnect/firewall/discover/identity/reputation/pricing/session/sandbox/team/zkp
│   │   ├── payment/        #   lango payment balance/history/limits/info/send
│   │   ├── prompt/         #   interactive prompt utilities
│   │   ├── provenance/     #   lango provenance status/checkpoint/session/attribution/bundle
│   │   ├── run/            #   lango run list/status/journal
│   │   ├── sandbox/        #   lango sandbox status/test
│   │   ├── security/       #   lango security status/secrets/change-passphrase/recovery/keyring/db-migrate/db-decrypt/kms
│   │   ├── settings/       #   lango settings (full configuration editor)
│   │   ├── smartaccount/   #   lango account info/deploy/session/module/policy/paymaster
│   │   ├── status/         #   lango status (unified dashboard)
│   │   ├── tui/            #   TUI components and views
│   │   └── workflow/       #   lango workflow run/list/status/cancel/history
│   ├── config/             # Config loading, env var substitution, validation
│   ├── configstore/        # Encrypted config profile storage (Ent-backed)
│   ├── ctxkeys/            # Context key helpers for agent name propagation
│   ├── a2a/                # A2A protocol server and remote agent loading
│   ├── economy/             # P2P economy layer (budget, risk, pricing, negotiation, escrow)
│   │   ├── budget/          #   Task budget allocation and tracking
│   │   ├── escrow/          #   Milestone escrow engine, on-chain settlement
│   │   │   ├── hub/         #     Hub/Vault settlers, contract clients
│   │   │   └── sentinel/    #     Security Sentinel anomaly detection
│   │   ├── negotiation/     #   P2P price negotiation protocol
│   │   ├── pricing/         #   Dynamic pricing with trust/volume discounts
│   │   └── risk/            #   Trust-based risk assessment
│   ├── agentrt/            # Agent runtime control plane (coordinating executor, delegation guard, budget, recovery)
│   ├── automation/         # Automation module helpers
│   ├── deadline/           # Deadline extension and auto-extend logic
│   ├── embedding/          # Embedding providers (OpenAI, Google, local) and RAG
│   ├── ent/                # Ent ORM schemas and generated code
│   ├── eventbus/           # Typed synchronous event pub/sub
│   ├── gatekeeper/         # Response sanitization (thought tags, internal markers, raw JSON, custom patterns)
│   ├── gateway/            # WebSocket/HTTP server, OIDC auth
│   ├── graph/              # BoltDB triple store, Graph RAG, entity extractor
│   ├── knowledge/          # Knowledge store, 8-layer context retriever
│   ├── learning/           # Learning engine, error pattern analyzer, self-learning graph
│   ├── lifecycle/          # Component lifecycle management (priority-ordered startup/shutdown)
│   ├── llm/                # LLM abstraction layer
│   ├── logging/            # Zap structured logger
│   ├── memory/             # Observational memory (observer, reflector, token counter)
│   ├── orchestration/      # Multi-agent orchestration (operator, navigator, vault, librarian, automator, planner, chronicler, ontologist)
│   ├── keyring/            # Hardware keyring integration (Touch ID / TPM 2.0)
│   ├── mdparse/            # Markdown frontmatter parser (YAML extraction)
│   ├── prompt/             # System prompt builder, section loader, defaults
│   ├── provenance/         # Session provenance (checkpoints, session tree, attribution, bundles)
│   ├── provider/           # AI provider interface and implementations
│   │   ├── anthropic/      #   Claude models
│   │   ├── gemini/         #   Google Gemini models
│   │   └── openai/         #   OpenAI-compatible (GPT, Ollama, etc.)
│   ├── retrieval/          # Retrieval coordinator (FactSearch, TemporalSearch, ContextSearch)
│   ├── runledger/          # RunLedger / Task OS (durable execution, journal, validators, planner)
│   ├── sandbox/            # Tool execution isolation (subprocess/container/OS-level)
│   ├── search/             # FTS5 search substrate (domain-agnostic full-text CRUD)
│   ├── security/           # Crypto providers, key registry, secrets store, companion discovery, KMS providers
│   ├── session/            # Ent-based SQLite session store
│   ├── skill/              # File-based skill system (SKILL.md parser, FileSkillStore, registry, executor, GitHub importer with git clone + HTTP fallback, resource directories)
│   ├── storeutil/          # Database store utilities
│   ├── contract/            # EVM smart contract interaction, ABI cache
│   ├── cron/               # Cron scheduler (robfig/cron/v3), job store, executor, delivery
│   ├── background/         # Background task manager, notifications, monitoring
│   ├── workflow/            # DAG workflow engine, YAML parser, state persistence
│   ├── turnrunner/         # Turn execution runner
│   ├── turntrace/          # Turn trace recording and analysis
│   ├── payment/            # Blockchain payment service (USDC on EVM chains, X402 audit trail)
│   ├── observability/       # Metrics, token tracking, health checks, audit logging
│   ├── p2p/                # P2P networking (libp2p node, identity, handshake, firewall, discovery, ZKP)
│   │   ├── agentpool/      #   Agent pool with health checking and weighted selection
│   │   ├── discovery/      #   GossipSub agent card propagation, credential revocation
│   │   ├── firewall/       #   Default deny-all ACL with per-peer, per-tool rules
│   │   ├── handshake/      #   ZK-enhanced authentication, session store, nonce cache
│   │   ├── identity/       #   DID identity derivation (did:lango:<pubkey>)
│   │   ├── paygate/        #   Payment gate, ledger, trust-based pricing
│   │   ├── protocol/       #   P2P protocol handler, remote agent, message types
│   │   ├── reputation/     #   Trust score tracking based on exchange outcomes
│   │   ├── settlement/     #   On-chain USDC settlement (EIP-3009)
│   │   ├── team/           #   P2P team coordination with conflict resolution
│   │   └── zkp/            #   ZK proofs (Plonk/Groth16), circuits (ownership, balance, capability, attestation)
│   ├── smartaccount/       # ERC-7579 smart accounts (Safe-based, ERC-4337 account abstraction)
│   │   ├── bindings/       #   Contract ABI bindings (Safe7579, SessionValidator, SpendingHook, EscrowExecutor)
│   │   ├── bundler/        #   ERC-4337 UserOp bundler client
│   │   ├── module/         #   ERC-7579 module registry and ABI encoder
│   │   ├── paymaster/      #   Gasless USDC transactions (Circle, Pimlico, Alchemy providers)
│   │   ├── policy/         #   Spending policy engine, on-chain syncer, validator
│   │   └── session/        #   Hierarchical session key management, crypto, store
│   ├── supervisor/         # Provider proxy, privileged tool execution
│   ├── testutil/           # Test mocks and helpers (crypto, embedding, graph, provider, session)
│   ├── wallet/             # Wallet providers (local, rpc, composite), spending limiter
│   ├── x402/               # X402 V2 payment protocol (Coinbase SDK, EIP-3009 signing)
│   ├── mcp/                # MCP server connection, tool adaptation, multi-scope config
│   ├── toolcatalog/        # Thread-safe tool registry with categories
│   ├── toolchain/          # Middleware chain for tool wrapping
│   ├── tools/              # browser, crypto, exec, filesystem, secrets, payment
│   └── types/              # Shared types (ProviderType, Role, RPCSenderFunc)
├── contracts/              # Foundry-based Solidity contracts (LangoEscrowHub, LangoVault, LangoVaultFactory)
├── prompts/                # Default prompt .md files (embedded via go:embed)
├── skills/                 # Skill system scaffold (go:embed). Built-in skills were removed — Lango's passphrase-based security model makes it impractical for the agent to invoke CLI commands as skills
└── openspec/               # Specifications (OpenSpec workflow)

AI Providers

Lango supports multiple AI providers with a unified interface. Provider aliases are resolved automatically (e.g., gpt/chatgpt -> openai, claude -> anthropic, llama -> ollama, bard -> gemini).

Supported Providers

Recommended: You should select a reasoning model for smooth usage.

• OpenAI (openai): Open-AI GPTs(GPT-5.2, GPT-5.3 Codex...), and OpenAI-Compatible APIs
• Anthropic (anthropic): Claude Opus, Sonnet, Haiku
• Gemini (gemini): Google Gemini Pro, Flash
• Ollama (ollama): Local models via Ollama (default: http://localhost:11434/v1)

Setup

Use lango onboard for guided first-time setup (5-step wizard), or lango settings for the full interactive configuration editor with free navigation across all options.

Configuration Reference

All settings are managed via lango onboard (guided wizard), lango settings (full editor), or lango config CLI and stored encrypted in the profile database.

On-Chain Economy (Base Sepolia Testnet)

Lango smart contracts are deployed on Base Sepolia (chain ID 84532). These are shared infrastructure contracts — all Lango agents use the same deployed instances.

Deployed Contract Addresses

Full deployment manifest: contracts/deployments/84532.json

Configuration

Enable on-chain economy with the deployed Base Sepolia contracts. Export your profile, add the settings, and re-import:

lango config export default > /tmp/config.json
# Edit /tmp/config.json to add the economy, smartAccount, and payment settings below
lango config import /tmp/config.json --profile default

Add these settings to your config JSON:

{
  "economy": {
    "enabled": true,
    "escrow": {
      "enabled": true,
      "onChain": {
        "enabled": true,
        "mode": "hub",
        "hubAddress": "0x1820A1C403A5811660a4893Ae028862208e4f7A8",
        "vaultFactoryAddress": "0x1CA47128D7fdDD0D875C3AeC7274C894F2c792C2",
        "vaultImplementation": "0x18167Daeca7A09B32D8BE93c73737B95B64A7ff8",
        "arbitratorAddress": "0x4BDBDE4A725A83820B7A94cD5dB523eb4515dDAd",
        "tokenAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
      }
    }
  },
  "smartAccount": {
    "enabled": true,
    "modules": {
      "sessionValidatorAddress": "0xB52877B5E27F77795Fbe59101D07CA81dbd3f8aC",
      "spendingHookAddress": "0xc428774991dBDf6645E254be793cb93A66cd9b4B",
      "escrowExecutorAddress": "0x5d08310987C5B59cB03F01363142656C5AE23997"
    }
  },
  "payment": {
    "enabled": true,
    "network": {
      "chainId": 84532,
      "rpcUrl": "https://sepolia.base.org",
      "usdcContract": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
    }
  }
}

Getting Testnet USDC

1. Get Base Sepolia ETH from the Base Faucet
2. Get testnet USDC from the Circle Faucet (select Base Sepolia)

Escrow Modes

• Hub mode (economy.escrow.onChain.mode: "hub") — All deals go through the shared LangoEscrowHub. Simpler, single contract manages all escrows.
• Vault mode (economy.escrow.onChain.mode: "vault") — Each deal gets its own LangoVault clone via LangoVaultFactory. Better isolation per deal.

Redeploying Contracts

To deploy your own instance (e.g., for local development):

cd contracts
cp .env.example .env   # fill in BASESCAN_API_KEY

# Import your wallet key into Foundry encrypted keystore (one-time)
cast wallet import my-deployer --interactive

# Deploy with canonical USDC
forge script script/Deploy.s.sol \
  --rpc-url base_sepolia \
  --account my-deployer \
  --sender <YOUR_ADDRESS> \
  --broadcast --verify -vvvv

# Deploy with MockUSDC (for testing)
DEPLOY_MOCK_USDC=true forge script script/Deploy.s.sol \
  --rpc-url base_sepolia \
  --account my-deployer \
  --sender <YOUR_ADDRESS> \
  --broadcast -vvvv

Deployed addresses are written to contracts/deployments/<chainId>.json.

System Prompts

Lango ships with production-quality default prompts embedded in the binary. No configuration is needed — the agent works out of the box with prompts covering identity, safety, conversation rules, and tool usage guidelines.

Prompt Sections

Customizing Prompts

Create a directory with .md files matching the section names above and set agent.promptsDir:

mkdir -p ~/.lango/prompts
# Override just the identity section
echo "You are a helpful coding assistant." > ~/.lango/prompts/AGENTS.md

Then configure the path via lango onboard > Agent Configuration > Prompts Directory, or set it in a config JSON:

{
  "agent": {
    "promptsDir": "~/.lango/prompts"
  }
}

Precedence: promptsDir (directory) > systemPromptPath (legacy single file) > built-in defaults.

Unknown .md files in the directory are added as custom sections with priority 900+, appearing after the default sections.

Per-Agent Prompt Customization

In multi-agent mode (agent.multiAgent: true), all sub-agents (operator, navigator, vault, librarian, automator, planner, chronicler, ontologist) automatically inherit shared prompt sections (Safety, Conversation Rules) from the prompts directory.

You can override or extend prompts per agent by creating an agents/<name>/ subdirectory:

~/.lango/prompts/
  AGENTS.md               # orchestrator identity
  SAFETY.md               # shared safety (inherited by all sub-agents)
  CONVERSATION_RULES.md   # shared rules (inherited by all sub-agents)
  agents/
    operator/
      IDENTITY.md          # override operator's default role description
      SAFETY.md            # override shared safety for operator only
    librarian/
      IDENTITY.md          # override librarian's default role description
      MY_RULES.md          # add custom section for librarian only

Supported per-agent files:

If no agents/<name>/ directory exists, the sub-agent uses its built-in instruction combined with the shared Safety and Conversation Rules.

Embedding & RAG

Lango supports embedding-based retrieval-augmented generation (RAG) to inject relevant context into agent prompts automatically.

Build tag required: The default build uses FTS5-only search. To enable semantic vector search (embedding/RAG), build with -tags "fts5,vec". Without the vec tag, the embedding system gracefully degrades and vector operations are skipped.

Supported Providers

• OpenAI (openai): text-embedding-3-small, text-embedding-3-large, etc.
• Google (google): Gemini embedding models
• Local (local): Ollama-compatible local embedding server

Configuration

Configure embedding and RAG settings via lango onboard > Embedding & RAG menu, or use lango config CLI.

RAG

When embedding.rag.enabled is true, relevant knowledge entries are automatically retrieved via vector similarity search and injected into the agent's context. Configure maxResults to control how many results are included and collections to limit which knowledge collections are searched.

Embedding Cache

Query embedding vectors are cached in-memory with a 5-minute TTL and 100-entry limit to reduce redundant API calls. The cache is automatic — no configuration needed.

Use lango doctor to verify embedding configuration and provider connectivity.

Knowledge Graph & Graph RAG

Lango includes a BoltDB-backed knowledge graph that stores relationships as Subject-Predicate-Object triples with three index orderings (SPO, POS, OSP) for efficient queries from any direction.

Predicate Vocabulary

Graph RAG (Hybrid Retrieval)

When both embedding/RAG and graph store are enabled, Lango uses 2-phase hybrid retrieval:

1. Vector Search — standard embedding-based similarity search
2. Graph Expansion — expands vector results through graph relationships (related_to, resolved_by, caused_by, similar_to)

This combines semantic similarity with structural knowledge for richer context.

Self-Learning Graph

The learning.GraphEngine automatically records error patterns and fixes as graph triples, with confidence propagation (rate 0.3) that strengthens frequently-confirmed relationships.

Configuration

Configure via lango onboard > Graph Store menu. Use lango graph status, lango graph stats, and lango graph query to inspect graph data.

Multi-Agent Orchestration

When agent.multiAgent is enabled, Lango builds a hierarchical agent tree with specialized sub-agents:

The orchestrator uses a keyword-based routing table and 5-step decision protocol (CLASSIFY → MATCH → SELECT → VERIFY → DELEGATE) to route tasks. Each sub-agent can reject misrouted tasks with [REJECT]. Unmatched tools are tracked separately and reported to the orchestrator.

Custom Agents (AGENT.md)

Custom agents can be defined via AGENT.md files placed in the agent.agentsDir directory. Each file specifies the agent's name, description, capabilities, and tool access. The agent registry loads these definitions at startup and makes them available for dynamic routing alongside built-in sub-agents.

Dynamic Routing

In addition to prefix-based tool partitioning, the orchestrator supports dynamic routing via keyword + capability matching. When a task does not match a prefix rule, the router evaluates registered agent capabilities and keywords to find the best-fit agent.

Agent Memory

When agentMemory.enabled is true, each sub-agent maintains its own persistent memory store for cross-session context retention. This allows agents to accumulate domain-specific knowledge across conversations, improving task performance over time.

Enable via lango onboard > Multi-Agent menu or set agent.multiAgent: true in import JSON. Use lango agent status and lango agent list to inspect.

A2A Protocol (🧪 Experimental Features)

Lango supports the Agent-to-Agent (A2A) protocol for inter-agent communication:

• Agent Card — served at /.well-known/agent.json with agent name, description, skills
• Remote Agents — discover and integrate external A2A agents as sub-agents in the orchestrator
• Graceful Degradation — unreachable remote agents are skipped without blocking startup

Configure via lango onboard > A2A Protocol menu. Remote agents (name + URL pairs) should be configured via lango config export → edit JSON → lango config import.

Note: All settings are stored in the encrypted profile database — no plaintext config files. Use lango onboard for interactive configuration or lango config import/export for programmatic configuration.

P2P Network (🧪 Experimental Features)

Lango supports decentralized peer-to-peer agent connectivity via the Sovereign Agent Network (SAN):

• libp2p Transport — TCP/QUIC with Noise encryption
• DID Identity — did:lango:<pubkey> derived from wallet keys
• Knowledge Firewall — Default deny-all ACL with per-peer, per-tool rules and rate limiting
• Agent Discovery — GossipSub-based agent card propagation with capability search
• ZK Handshake — Optional zero-knowledge proof verification during authentication
• ZK Attestation — Prove response authenticity without revealing internal state
• Payment Gate — USDC-based paid tool invocations with configurable per-tool pricing
• Approval Pipeline — Three-stage inbound gate (firewall → owner approval → execution) with auto-approve for paid tools below threshold
• Reputation System — Trust score tracking based on exchange outcomes (successes, failures, timeouts)
• Owner Shield — PII protection that sanitizes outgoing P2P responses to prevent owner data leakage
• Signed Challenges — ECDSA signed handshake challenges with nonce replay protection and timestamp validation
• Session Management — TTL + explicit session invalidation with security event auto-revocation
• Tool Sandbox — Subprocess and container-based isolation for remote tool execution
• Cloud KMS / HSM — AWS KMS, GCP KMS, Azure Key Vault, PKCS#11 HSM integration for signing and encryption
• Database Encryption — SQLCipher transparent encryption for the application database
• OS Keyring — Hardware-backed passphrase storage in OS keyring (macOS Keychain, Linux secret-service, Windows DPAPI)
• Credential Revocation — DID revocation and max credential age enforcement via gossip
• Trust-Based Pricing — Tiered pricing model: PostPay for trusted peers (reputation score >= 0.8), PrePay for new/untrusted peers
• Settlement Service — Async on-chain USDC settlement via EIP-3009 with receipt tracking and configurable retry
• Auto-Payment Tool — p2p_invoke_paid tool for buyer-side automatic payment handling during P2P interactions
• P2P Teams — Task-scoped agent groups with role-based delegation (Leader, Worker, Reviewer, Observer), conflict resolution, and result aggregation
• Agent Pool — P2P agent pool with discovery integration, periodic health checking, and weighted selection based on reputation scores

Paid Value Exchange

Lango supports monetized P2P tool invocations. Peers can set prices for their tools in USDC, and callers follow a structured flow:

1. Discover peers with the desired capability
2. Check reputation to verify peer trustworthiness
3. Query pricing to see the cost before committing
4. Send payment in USDC via on-chain transfer
5. Invoke the tool after payment confirmation

Auto-Approval: Payments below payment.limits.autoApproveBelow are auto-approved without confirmation, provided they also satisfy maxPerTx and maxDaily limits.

Configure pricing in the P2P config:

{
  "pricing": {
    "enabled": true,
    "perQuery": "0.10",
    "toolPrices": {
      "knowledge_search": "0.25"
    }
  }
}

REST API

When the gateway is running, P2P status endpoints are available for monitoring and automation:

curl http://localhost:18789/api/p2p/status     # Peer ID, listen addrs, peer count
curl http://localhost:18789/api/p2p/peers      # Connected peers with addrs
curl http://localhost:18789/api/p2p/identity   # Local DID and peer ID
curl "http://localhost:18789/api/p2p/reputation?peer_did=did:lango:02abc..."  # Trust score
curl http://localhost:18789/api/p2p/pricing    # Tool pricing

CLI Usage

# Check node status
lango p2p status

# List connected peers
lango p2p peers

# Connect to a peer
lango p2p connect /ip4/1.2.3.4/tcp/9000/p2p/QmPeerId

# Discover agents by capability
lango p2p discover --tag research

# Manage firewall rules
lango p2p firewall list
lango p2p firewall add --peer-did "did:lango:02abc..." --action allow --tools "search_*"

# Show identity
lango p2p identity

# Manage peer sessions
lango p2p session list
lango p2p session revoke --peer-did "did:lango:02abc..."
lango p2p session revoke-all

# Sandbox management
lango p2p sandbox status
lango p2p sandbox test
lango p2p sandbox cleanup

Configuration

Configure via lango settings → P2P Network, or import JSON with lango config import. Requires security.signer to be configured for wallet-based DID derivation.

Blockchain Payments (🧪 Experimental Features)

Lango includes a blockchain payment system for USDC transactions on Base L2 (EVM), with built-in spending limits and X402 protocol support.

Payment Tools

When payment.enabled is true, the following agent tools are registered:

Wallet Providers

X402 V2 Protocol

Lango uses the official Coinbase X402 Go SDK for automatic HTTP 402 payments. When payment.x402.autoIntercept is enabled:

1. Agent makes an HTTP request via the payment_x402_fetch tool
2. Server returns 402 with PAYMENT-REQUIRED header (Base64 JSON)
3. SDK's PaymentRoundTripper intercepts the 402 response
4. SDK creates an EIP-3009 transferWithAuthorization, signs with EIP-712 typed data
5. SDK retries the request with PAYMENT-SIGNATURE header
6. Server verifies the signature and returns content

Key features:

• EIP-3009 off-chain signatures — no on-chain transaction needed from the agent
• CAIP-2 network identifiers — standard eip155:<chainID> format
• Spending limit enforcement — BeforePaymentCreationHook checks per-tx and daily limits before signing
• Lazy client initialization — wallet key loaded only when first X402 request is made
• Audit trail — X402 payments recorded in PaymentTx with payment_method = "x402_v2"

CLI Usage

# Check wallet balance
lango payment balance

# View transaction history
lango payment history --limit 10

# View spending limits
lango payment limits

# Show wallet and network info
lango payment info

# Send USDC (interactive confirmation)
lango payment send --to 0x... --amount 0.50 --purpose "API access"

# Send USDC (non-interactive)
lango payment send --to 0x... --amount 0.50 --purpose "API access" --force

# JSON output for scripting
lango payment balance --json

Configuration

Configure via lango onboard or import JSON with lango config import. Requires security.signer to be configured for wallet key management.

Cron Scheduling

Lango includes a persistent cron scheduling system powered by robfig/cron/v3 with Ent ORM storage. Jobs survive server restarts and deliver results to configured channels.

Schedule Types

CLI Usage

# Add a daily news summary delivered to Slack
lango cron add --name "news" --schedule "0 9 * * *" --prompt "Summarize today's news" --deliver slack

# Add hourly server check with timezone
lango cron add --name "health" --every 1h --prompt "Check server status" --timezone "Asia/Seoul"

# Add one-time reminder
lango cron add --name "meeting" --at "2026-02-20T15:00:00" --prompt "Prepare meeting notes"

# Manage jobs
lango cron list
lango cron pause news
lango cron resume news
lango cron delete news
lango cron history news

Each job runs in an isolated session (cron:<name>:<timestamp>) by default. Use --isolated=false for shared session mode.

Background Execution (🧪 Experimental Features)

Lango provides an in-memory background task manager for async agent operations with concurrency control.

Features

• Concurrency Limiting — configurable max concurrent tasks via semaphore
• Task State Machine — Pending -> Running -> Done/Failed/Cancelled with mutex-protected transitions
• Completion Notifications — results delivered to the origin channel automatically
• Monitoring — active task count and summary tracking

Background tasks are ephemeral (in-memory only) and do not persist across server restarts.

Workflow Engine (🧪 Experimental Features)

Lango includes a DAG-based workflow engine that executes multi-step workflows defined in YAML. Steps run in parallel when dependencies allow, with results flowing between steps via template variables.

Workflow YAML Format

name: code-review-pipeline
description: "Automated PR code review"
deliver_to: [slack]

steps:
  - id: fetch-changes
    agent: executor
    prompt: "Get git diff main...HEAD"

  - id: security-scan
    agent: researcher
    prompt: "Analyze security in: {{fetch-changes.result}}"
    depends_on: [fetch-changes]

  - id: quality-review
    agent: researcher
    prompt: "Review code quality: {{fetch-changes.result}}"
    depends_on: [fetch-changes]

  - id: summary
    agent: planner
    prompt: |
      Security: {{security-scan.result}}
      Quality: {{quality-review.result}}
      Write a review report.
    depends_on: [security-scan, quality-review]
    deliver_to: [slack]

Features

• DAG Execution — topological sort produces parallel layers; independent steps run concurrently
• Template Variables — {{step-id.result}} substitution using Go templates
• State Persistence — Ent ORM-backed WorkflowRun/WorkflowStepRun for resume capability
• Step-Level Delivery — individual steps can deliver results to channels
• Cycle Detection — DFS-based validation prevents circular dependencies

CLI Usage

# Run a workflow
lango workflow run code-review.flow.yaml

# Monitor execution
lango workflow list
lango workflow status <run-id>

# Cancel and inspect history
lango workflow cancel <run-id>
lango workflow history

Supported Agents

Steps specify which sub-agent to use: operator, navigator, vault, librarian, automator, planner, chronicler, or ontologist. These map to the multi-agent orchestration system when agent.multiAgent is enabled.

Self-Learning System

Lango includes a self-learning knowledge system that improves agent performance over time.

• Knowledge Store - Persistent storage for facts, patterns, and external references
• Learning Engine - Observes tool execution results, extracts error patterns, boosts successful strategies. Agent tools (learning_stats, learning_cleanup) let the agent brief users on learning data and clean up entries by age, confidence, or category
• Skill System - File-based skills stored as ~/.lango/skills/<name>/SKILL.md with YAML frontmatter. Supports four skill types: script (shell), template (Go template), composite (multi-step), and instruction (reference documents). Previously shipped ~30 built-in skills, but these were removed because Lango's passphrase-based security model makes it impractical for the agent to invoke CLI commands as skills. The skill infrastructure remains fully functional for user-defined skills. Import skills from GitHub repos or any URL via the import_skill tool — automatically uses git clone when available (fetches full directory with resource files) and falls back to the GitHub HTTP API when git is not installed. Each skill directory can include resource subdirectories (scripts/, references/, assets/). YAML frontmatter supports allowed-tools for pre-approved tool lists. Dangerous script patterns (fork bombs, rm -rf /, curl|sh) are blocked at creation and execution time.
• Context Retriever - 8-layer context architecture that assembles relevant knowledge into prompts:
  1. Tool Registry — available tools and capabilities
  2. User Knowledge — rules, preferences, definitions, facts
  3. Skill Patterns — known working tool chains and workflows
  4. External Knowledge — docs, wiki, MCP integration
  5. Agent Learnings — error patterns, discovered fixes
  6. Runtime Context — session history, tool results, env state
  7. Observations — compressed conversation observations
  8. Reflections — condensed observation reflections

Observational Memory

Observational Memory is an async subsystem that compresses long conversations into durable observations and reflections, keeping context relevant without exceeding token budgets.

• Observer — monitors conversation token count and produces compressed observations when the message token threshold is reached
• Reflector — condenses accumulated observations into higher-level reflections when the observation token threshold is reached
• Async Buffer — queues observation/reflection tasks for background processing
• Token Counter — tracks token usage to determine when compression should trigger
• Context Limits — only the most recent reflections (default: 5) and observations (default: 20) are injected into LLM context, keeping prompts lean as sessions grow

Configure knowledge and observational memory settings via lango onboard or lango config CLI. Use lango memory list, lango memory status, and lango memory clear to manage observation entries.

Security

Lango includes built-in security features for AI agents:

Security Configuration

Lango supports two security modes:

1. Local Mode (Default)

• Uses a Master Key (MK) envelope — a random 32-byte MK encrypts all data (AES-256-GCM), and the passphrase wraps the MK via a KEK.
• Interactive: Prompts for passphrase on startup (Recommended).
• Headless: Provide a keyfile at ~/.lango/keyfile (0600 permissions).
• Change passphrase (O(1), no data re-encryption):

  lango security change-passphrase
  

• Recovery mnemonic (BIP39 24-word backup):

  lango security recovery setup     # Generate and store mnemonic
  lango security recovery restore   # Recover access with mnemonic
  

Note: Without a recovery mnemonic, losing your passphrase results in permanent loss of all encrypted data. Set up recovery with lango security recovery setup.

1. RPC Mode (Production)

• Offloads cryptographic operations to a hardware-backed companion app or external signer.
• Keys never leave the secure hardware.

Configure security mode via lango onboard > Security menu, or use lango config CLI.

AI Privacy Interceptor

Lango includes a privacy interceptor that sits between the agent and AI providers:

• PII Redaction — automatically detects and redacts personally identifiable information before sending to AI providers, with 13 builtin patterns:
  • Contact: email, US phone, Korean mobile/landline, international phone
  • Identity: Korean RRN (주민등록번호), US SSN, driver's license, passport
  • Financial: credit card (Luhn-validated), Korean bank account, IBAN
  • Network: IPv4 addresses
• Pattern Customization — disable builtin patterns via piiDisabledPatterns or add custom regex via piiCustomPatterns
• Presidio Integration — optionally enable Microsoft Presidio for NER-based detection alongside regex (docker compose --profile presidio up)
• Approval Workflows — optionally require human approval before executing sensitive tools

Secret Management

Agents can manage encrypted secrets as part of their tool workflows. Secrets are stored using AES-256-GCM encryption and referenced by name, preventing plaintext values from appearing in logs or conversation history.

Output Scanning

The built-in secret scanner monitors agent output for accidental secret leakage. Registered secret values are automatically replaced with [SECRET:name] placeholders before being displayed or logged.

Key Registry

Lango manages cryptographic keys via an Ent-backed key registry. Keys are used for secret encryption, signing, and companion app integration.

Wallet Key Security

When blockchain payments are enabled, wallet private keys are protected by the same encryption layer as other secrets:

• Local mode: Keys are derived from the passphrase-encrypted secrets store (AES-256-GCM). Private keys never leave the wallet layer — the agent only sees addresses and receipts.
• RPC mode: Signing operations are delegated to the companion app / hardware signer.
• Spending limits: Per-transaction and daily limits prevent runaway spending. Limits are enforced in the wallet.SpendingLimiter before any transaction is signed.

Companion App Discovery (RPC Mode) (🧪 Experimental Features)

Lango supports optional companion apps for hardware-backed security. Companion discovery is handled within the internal/security module:

• mDNS Discovery — auto-discovers companion apps on the local network via _lango-companion._tcp
• Manual Config — set a fixed companion address

Hardware Keyring

Store the master passphrase in a hardware-backed keyring for automatic unlock on startup:

lango security keyring store    # Store passphrase in hardware backend
lango security keyring status   # Check hardware keyring availability
lango security keyring clear    # Remove stored passphrase

Supported: macOS Touch ID (Secure Enclave), Linux TPM 2.0. Plain OS keyring is not supported due to same-UID attack risks.

Database Encryption

Encrypt the application database at rest using SQLCipher:

lango security db-migrate    # Encrypt plaintext DB
lango security db-decrypt    # Decrypt back to plaintext

Configure via security.dbEncryption.enabled and security.dbEncryption.cipherPageSize (default: 4096).

Cloud KMS / HSM

Delegate cryptographic operations to managed key services:

lango security kms status    # Check KMS connection
lango security kms test      # Test encrypt/decrypt roundtrip
lango security kms keys      # List registered keys

Set security.signer.provider to the desired KMS backend and configure security.kms.* settings.

P2P Security Hardening

The P2P network includes multiple security layers:

• Signed Challenges — ECDSA signed handshake (nonce || timestamp || DID), timestamp validation (5min past + 30s future), nonce replay protection
• Session Management — TTL + explicit invalidation with auto-revocation on reputation drop or repeated failures
• Tool Sandbox — Subprocess and container-based process isolation for remote tool execution
• Credential Revocation — DID revocation set and max credential age enforcement via gossip discovery

Authentication

Lango supports OIDC authentication for the gateway. Configure OIDC providers via lango onboard > Auth menu, or include them in a JSON config file and import with lango config import.

Auth Endpoints

Protected Routes

When OIDC is configured, the following endpoints require a valid lango_session cookie:

• /ws — WebSocket connection
• /status — Server status

Without OIDC configuration, all routes are open (development/local mode).

WebSocket CORS

Use server.allowedOrigins to control which origins can connect via WebSocket:

• [] (empty, default) — same-origin requests only
• ["https://example.com"] — specific origins
• ["*"] — allow all origins (not recommended for production)

WebSocket Events

The gateway broadcasts the following events during chat processing:

Events are scoped to the requesting user's session. Clients that don't handle agent.chunk will still receive the full response in the RPC result (backward compatible).

Rate Limiting

Auth endpoints (/auth/login/*, /auth/callback/*, /auth/logout) are throttled to a maximum of 10 concurrent requests.

Docker

Docker Image

The Docker image includes Chromium for browser automation, plus git and curl for skill import and general-purpose operations:

docker build -t lango:latest .

Docker Compose

docker compose up -d

Headless Configuration

The Docker image includes an entrypoint script that auto-imports configuration on first startup. Both the config and passphrase are injected via Docker secrets — never as environment variables — so the agent cannot read them at runtime.

1. Create config.json with your provider keys and settings.
2. Create passphrase.txt containing your encryption passphrase.
3. Run with docker-compose:

 docker compose up -d

The entrypoint script (docker-entrypoint.sh):

• Copies the passphrase secret to ~/.lango/keyfile (0600, blocked by the agent's filesystem tool)
• On first run, copies the config secret to /tmp, imports it into an encrypted profile, and the temp file is auto-deleted
• On subsequent restarts, the existing profile is reused

Environment variables (optional):

• LANGO_PROFILE — profile name to create (default: default)
• LANGO_CONFIG_FILE — override config secret path (default: /run/secrets/lango_config)
• LANGO_PASSPHRASE_FILE — override passphrase secret path (default: /run/secrets/lango_passphrase)

Examples

P2P Trading (Docker Compose)

A complete multi-agent integration example with 3 Lango agents (Alice, Bob, Charlie) trading USDC on a local Ethereum chain:

• P2P Discovery — agents discover each other via mDNS
• DID Identity — did:lango: identifiers derived from wallet keys
• USDC Payments — MockUSDC contract on Anvil (local EVM)
• E2E Tests — automated health, discovery, balance, and transfer verification

cd examples/p2p-trading
make all    # Build, start, wait for health, run tests, shut down

See [examples/p2p-trading/README.md](examples/p2p-trading/README.md) for architecture details and prerequisites.

Development

# Run tests with race detector
make test

# Run linter
make lint

# Build for all platforms
make build-all

# Run locally (build + serve)
make dev

# Generate Ent code
make generate

# Download and tidy dependencies
make deps

License

MIT